7.0 KiB
Implementation Plan: Family Office UI Redesign
Branch: 008-fo-ui-redesign | Date: 2026-03-22 | Spec: spec.md
Input: Feature specification from /specs/008-fo-ui-redesign/spec.md
Summary
Redesign the UI to surface existing family office data (K1 income, partnership performance, distributions) in the portfolio analysis view and restructure navigation around five family office-focused top-level items. The backend APIs and data services already exist — FamilyOfficeService computes portfolio summaries, asset class breakdowns, activity ledgers, and periodic reports, and FamilyOfficeDataService on the client has HTTP wrappers for all five endpoints. However, zero Angular components consume the four richest endpoints (portfolio-summary, asset-class-summary, activity, report). The work is primarily frontend: wire existing client-side data methods into the portfolio analysis page, restructure the header navigation into grouped menus, and enhance the existing family dashboard to be the default landing page.
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), chart.js 4.5.1, date-fns 4.1.0, Bull 4.16.5 (queues), Redis (caching), Ionic 8.8.1
Storage: PostgreSQL via Prisma ORM, Redis for caching
Testing: Jest 30.2.0 (via @nx/jest), jest-preset-angular 16.0.0 for client tests
Target Platform: Linux server (Docker/Railway), web browser (Angular SPA)
Project Type: Nx monorepo web application (API + Client + 2 shared libs)
Performance Goals: Dashboard load < 5s, portfolio analysis with K1 data < 3s (SC-001, SC-005)
Constraints: Preserve all existing Ghostfolio functionality; all legacy URLs must keep working (SC-004); no breaking API changes
Scale/Scope: Single family office (1-5 users), ~50 entities/partnerships, ~100 K1 documents, 5 primary nav items
Constitution Check
GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.
| # | Constitution Principle | Status | Notes |
|---|---|---|---|
| I | Nx Monorepo Structure | PASS | All changes in existing 4 projects (api, client, common, ui). No new Nx projects. |
| II | NestJS Module Pattern | PASS | No new backend modules needed. Existing FamilyOfficeModule already exposes all required endpoints. Minor additions only if new aggregation endpoints are needed. |
| III | Prisma Data Layer | PASS | No schema changes required. All data models already exist. |
| IV | TypeScript Strict Conventions | PASS | Standard — no dead code, path aliases. |
| V | Simplicity First / YAGNI | PASS | This feature wires existing unused APIs into existing UI pages. No new abstractions. Maximum reuse of FamilyOfficeDataService methods already built. |
| VI | Interface-First Design | PASS | All interfaces already defined in @ghostfolio/common (IFamilyOfficeDashboard, IPortfolioSummary, IAssetClassSummary, IActivityDetail, IFamilyOfficeReport). |
Pre-Phase 0 Gate: All 6 principles PASS. No violations.
Post-Phase 1 Re-check:
| # | Constitution Principle | Status | Notes |
|---|---|---|---|
| I | Nx Monorepo Structure | PASS | All changes within existing 4 projects. 3 new components in libs/ui, modifications to apps/client pages and header. No new Nx projects. |
| II | NestJS Module Pattern | PASS | No backend changes required. All API endpoints already exist in FamilyOfficeModule. |
| III | Prisma Data Layer | PASS | No schema changes. No new migrations. |
| IV | TypeScript Strict Conventions | PASS | All new code follows strict mode. Path aliases used consistently. |
| V | Simplicity First / YAGNI | PASS | Feature wires 4 existing unused API endpoints to UI components. 3 new small UI components (k1-income-summary, nav-menu-group, performance-metrics-card). No new abstractions or architectural layers. Maximum reuse of existing FamilyOfficeDataService and libs/ui components. |
| VI | Interface-First Design | PASS | All interfaces already defined in @ghostfolio/common (IFamilyOfficeDashboard, IPortfolioSummary, IAssetClassSummary, IActivityDetail, IFamilyOfficeReport). No new shared interfaces needed. |
Post-Phase 1 Gate: All 6 principles PASS. Design adds 3 new libs/ui components and modifies 6 existing files. No violations.
Project Structure
Documentation (this feature)
specs/008-fo-ui-redesign/
├── plan.md # This file
├── research.md # Phase 0 output
├── data-model.md # Phase 1 output
├── quickstart.md # Phase 1 output
├── contracts/ # Phase 1 output (navigation contract, analysis data shape)
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
Source Code (repository root)
apps/client/src/app/
├── components/
│ └── header/
│ ├── header.component.ts # MODIFIED: Restructure nav to 5 grouped items
│ └── header.component.html # MODIFIED: New nav template with submenus
├── pages/
│ ├── portfolio/
│ │ └── analysis/
│ │ ├── analysis-page.component.ts # MODIFIED: Add FO data integration
│ │ └── analysis-page.component.html # MODIFIED: Add K1 income sections
│ ├── family-dashboard/
│ │ ├── dashboard-page.component.ts # MODIFIED: Add portfolio summary, K1 income cards
│ │ └── dashboard-page.component.html # MODIFIED: Enhanced dashboard layout
│ └── home/
│ └── home-page.routes.ts # MODIFIED: Default redirect to family-dashboard
├── services/
│ └── family-office-data.service.ts # EXISTING: Already has all HTTP methods, no changes
└── app.routes.ts # MODIFIED: Update default route
libs/ui/src/lib/
├── k1-income-summary/ # NEW: Reusable K1 income breakdown card
│ ├── k1-income-summary.component.ts
│ └── k1-income-summary.component.html
├── performance-metrics-card/ # NEW: Reusable IRR/TVPI/DPI/RVPI card
│ ├── performance-metrics-card.component.ts
│ └── performance-metrics-card.component.html
└── nav-menu-group/ # NEW: Grouped nav item with expandable submenu
├── nav-menu-group.component.ts
└── nav-menu-group.component.html
Structure Decision: Follows the existing Nx monorepo structure. This is primarily a frontend feature — modifying existing Angular pages (portfolio analysis, family dashboard, header) and adding 3 small reusable UI components in libs/ui. No new NestJS modules, no Prisma schema changes, no new Nx projects. All within the existing 4-project structure (api, client, common, ui).
Complexity Tracking
No constitution violations to justify — all 6 principles pass.