ghostfolio/specs/001-family-office-transform/plan.md

Implementation Plan: Single Family Office Platform Transformation

Branch: 001-family-office-transform | Date: 2026-03-15 | Spec: spec.md Input: Feature specification from /specs/001-family-office-transform/spec.md

Summary

Transform the Ghostfolio portfolio management platform from a single-user investment tracker into a single family office platform. This adds entity management (trusts, LLCs, LPs, individuals), partnership tracking with ownership percentages and NAV valuations, distribution tracking with tax categorization, K-1/K-3 structured document management, private-market performance calculations (XIRR, TVPI, DPI, Modified Dietz), benchmark comparison overlays (S&P 500, bonds, real estate, CPI), and periodic consolidated reporting. The existing public-market portfolio tracking (accounts, orders, market data) is preserved and extended — entities become the new ownership layer above accounts and partnerships.

Technical Context

Language/Version: TypeScript 5.9.2, Node.js ≥22.18.0 Primary Dependencies: NestJS 11.1.14 (API), Angular 21.1.1 + Angular Material 21.1.1 (client), Prisma 6.19.0 (ORM), Nx 22.5.3 (monorepo), big.js (decimal math), date-fns 4.1.0, chart.js 4.5.1, Bull 4.16.5 (job queues), Redis (caching), yahoo-finance2 3.13.2 Storage: PostgreSQL via Prisma ORM, Redis for caching, local filesystem for document uploads Testing: Jest (via @nx/jest), jest-preset-angular for client tests, existing calculator specs in apps/api/src/app/portfolio/calculator/roai/ (21 spec files) Target Platform: Linux server (Docker), web browser (Angular SPA) Project Type: Nx monorepo web application (API + Client + 2 shared libs) Performance Goals: XIRR calculation < 5s for 4+ quarters, report generation < 15s, benchmark comparison < 10s Constraints: Preserve all existing Ghostfolio functionality (accounts, orders, market data, public portfolio tracking); no breaking changes to existing API contracts Scale/Scope: Single family office (1-5 admin users), ~50 entities/partnerships, ~500 distributions/year, ~100 K-1 documents

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

No constitution file exists (.specify/memory/constitution.md not found). No gates to evaluate. Design proceeds with these self-imposed constraints derived from existing codebase patterns:

1. Follow existing NestJS module pattern: Controller + Service + Module per domain area, DTOs in libs/common, PrismaService for DB access (no repository pattern)
2. Follow existing Angular standalone component pattern: Standalone components with lazy-loaded routes, Angular Material, Ionicons, takeUntilDestroyed cleanup
3. Use existing auth/guard stack: AuthGuard('jwt') + HasPermissionGuard + @HasPermission() decorator
4. Use existing exchange rate service: ExchangeRateDataService for all currency conversions
5. Use existing data provider service: DataProviderService for benchmark market data
6. Use Prisma migrations: New models via prisma migrate dev with standard migration naming
7. Shared types in libs/common: All interfaces, DTOs, enums shared between API and client live in @ghostfolio/common
8. Use big.js for financial math: Consistent with existing calculator precision approach

Post-Phase-1 Re-check: Design adds 9 new Prisma models, 8 new enums, 5 new NestJS modules, 9 new Angular pages, 6 new UI components. All follow existing patterns. No violations.

Project Structure

Documentation (this feature)

specs/001-family-office-transform/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output (REST API contracts)
└── tasks.md             # Phase 2 output (/speckit.tasks command)

Source Code (repository root)

prisma/
├── schema.prisma                          # Extended with 9 new models, 8 new enums
└── migrations/
    └── YYYYMMDDHHMMSS_family_office_models/  # Single migration for all new models

apps/api/src/app/
├── entity/                                # NEW: Entity management module
│   ├── entity.controller.ts
│   ├── entity.service.ts
│   ├── entity.module.ts
│   └── interfaces/
├── partnership/                           # NEW: Partnership management module
│   ├── partnership.controller.ts
│   ├── partnership.service.ts
│   ├── partnership.module.ts
│   └── interfaces/
├── distribution/                          # NEW: Distribution tracking module
│   ├── distribution.controller.ts
│   ├── distribution.service.ts
│   ├── distribution.module.ts
│   └── interfaces/
├── k-document/                            # NEW: K-1/K-3 document module
│   ├── k-document.controller.ts
│   ├── k-document.service.ts
│   ├── k-document.module.ts
│   └── interfaces/
├── family-office/                         # NEW: Consolidated FO operations
│   ├── family-office.controller.ts
│   ├── family-office.service.ts
│   └── family-office.module.ts
├── portfolio/
│   └── calculator/
│       └── family-office/                 # NEW: Private market calculators
│           ├── performance-calculator.ts
│           └── performance-calculator.spec.ts
└── upload/                                # NEW: File upload module
    ├── upload.controller.ts
    ├── upload.service.ts
    └── upload.module.ts

apps/api/src/services/
└── benchmark/
    └── family-office-benchmark.service.ts # NEW: Benchmark comparison overlay

libs/common/src/lib/
├── dtos/                                  # NEW DTOs for all family office entities
├── interfaces/                            # NEW interfaces for FO domain
├── enums/                                 # NEW enums mirroring Prisma enums
└── permissions.ts                         # MODIFIED: Add FO permissions

apps/client/src/app/
├── pages/
│   ├── entities/                          # NEW: Entity list page
│   ├── entity-detail/                     # NEW: Entity detail + ownership view
│   ├── partnerships/                      # NEW: Partnership list page
│   ├── partnership-detail/                # NEW: Partnership detail + members/assets
│   ├── partnership-performance/           # NEW: Performance + benchmark comparison
│   ├── distributions/                     # NEW: Distribution tracking page
│   ├── k-documents/                       # NEW: K-1/K-3 management page
│   ├── family-dashboard/                  # NEW: Consolidated FO dashboard
│   └── reports/                           # NEW: Periodic report generation
└── services/
    └── family-office-data.service.ts      # NEW: API client for FO endpoints

libs/ui/src/lib/
├── entity-card/                           # NEW: Entity summary card component
├── partnership-table/                     # NEW: Partnership members table
├── distribution-chart/                    # NEW: Distribution visualization
├── performance-metrics/                   # NEW: IRR/TVPI/DPI display component
├── benchmark-comparison-chart/            # NEW: Multi-benchmark overlay chart
└── k-document-form/                       # NEW: K-1 structured data entry form

Structure Decision: Follows the existing Nx monorepo structure. New NestJS modules in apps/api/src/app/, new Angular pages in apps/client/src/app/pages/, shared types/DTOs in libs/common/src/lib/, reusable UI components in libs/ui/src/lib/. No new Nx projects — all new code fits within the existing 4-project structure (api, client, common, ui).

Complexity Tracking

No constitution violations to justify — no constitution exists.