# Research: Family Office UI Redesign

**Feature**: 008-fo-ui-redesign
**Date**: 2026-03-22

## Research Questions & Findings

### R-001: How does the current navigation work and what needs to change?

**Decision**: Restructure the flat 11+ nav items into 5 grouped top-level items using Angular Material `mat-menu` dropdowns.

**Rationale**: The header component (`header.component.html`, 587 lines) currently renders 11 top-level `<li>` items in a toolbar `<ul>` for desktop, then duplicates them all as `mat-menu-item` entries inside the account dropdown for mobile. There are no nested/grouped menu patterns anywhere in the app today. The mat-menu component (`@angular/material/menu`) is already imported and used for the assistant and account menus, so extending it to navigation groups requires no new dependencies.

**Current navigation items (authenticated desktop)**:
1. Overview → `['/']`
2. Portfolio → `internalRoutes.portfolio`
3. Accounts → `internalRoutes.accounts`
4. Entities → `/entities`
5. Partnerships → `/partnerships`
6. Distributions → `/distributions`
7. K-1 Documents → `/k-documents`
8. K-1 Import → `/k1-import`
9. Cell Mapping → `/cell-mapping`
10. Portfolio Views → `/portfolio-views`
11. Admin Control (conditional)

**Target navigation structure**:
1. **Dashboard** → `/family-office` (existing route, currently at bottom of app.routes.ts)
2. **Partnerships** (mat-menu dropdown) → Entities, Partnerships, Distributions, Portfolio Views
3. **K-1 Center** (mat-menu dropdown) → K-1 Import, K-1 Documents, Cell Mapping
4. **Analysis** → existing `/portfolio` (portfolio analysis, activities, allocations)
5. **Admin** (conditional) → Admin Control, Accounts, Resources, Pricing

**Legacy pages** (moved to "More" or accessible only via URL): Overview, Holdings, Summary, Markets, Watchlist, FIRE, X-Ray

**Alternatives considered**:
- Sidebar navigation: Rejected — would require major layout restructuring, inconsistent with Ghostfolio's toolbar approach
- Keep flat list, just reorder: Rejected — 11+ items is too many, doesn't communicate hierarchy

---

### R-002: What family office data is available but not surfaced in portfolio analysis?

**Decision**: The portfolio analysis page must be modified to call `FamilyOfficeDataService` methods that already exist but have zero UI consumers.

**Rationale**: Research reveals a complete parallel data system:

| Available Endpoint | Interface | Client Method | Current UI Consumer |
|---|---|---|---|
| `GET /family-office/dashboard` | `IFamilyOfficeDashboard` | `fetchDashboard()` | Family Dashboard page ONLY |
| `GET /family-office/portfolio-summary` | `IPortfolioSummary` | `fetchPortfolioSummary()` | **NONE** |
| `GET /family-office/asset-class-summary` | `IAssetClassSummary` | `fetchAssetClassSummary()` | **NONE** |
| `GET /family-office/activity` | `IActivityDetail` | `fetchActivity()` | **NONE** |
| `GET /family-office/report` | `IFamilyOfficeReport` | `fetchReport()` | **NONE** |

The four richest endpoints have complete backend implementations in `FamilyOfficeService` (1453 lines), HTTP client wrappers in `FamilyOfficeDataService`, and typed interfaces in `@ghostfolio/common` — but **no Angular component uses them**.

**Key data shapes unused**:
- `IPortfolioSummary`: Entity-level IRR, TVPI, DPI, RVPI, original commitment, unfunded, paid-in, distributions
- `IAssetClassSummary`: Same metrics broken down by asset class
- `IActivityDetail`: Full K1 ledger with basis tracking, income decomposition (interest, dividends, capital gains, deductions), excess distributions
- `IFamilyOfficeReport`: Period performance, partnership-level returns, distribution summaries, benchmark comparisons

**Alternatives considered**:
- Add new API endpoints: Rejected — the data is already computed and exposed, just not consumed
- Modify `PortfolioService.getDetails()` to include K1 data: Rejected — would couple two separate data domains; better to add FO data alongside the existing view

---

### R-003: How should K1 data integrate into the portfolio analysis page?

**Decision**: Add a new section to the analysis page using `FamilyOfficeDataService` alongside the existing `DataService`, displaying family office metrics in new cards below the existing Ghostfolio analysis content.

**Rationale**: The current analysis page (`analysis-page.component.ts`, 296 lines) uses only `DataService` for standard Ghostfolio portfolio data. Rather than replacing this, add a conditional section that appears when family office data exists. This preserves backward compatibility and follows the spec requirement that legacy features remain functional.

**Integration approach**:
1. Inject `FamilyOfficeDataService` into the analysis page component
2. Call `fetchPortfolioSummary()` and `fetchAssetClassSummary()` on init
3. Add new template sections for: K1 income summary card, performance metrics (IRR/TVPI/DPI/RVPI), entity breakdown table, asset class breakdown table
4. Gate the new sections behind a check for non-empty family office data
5. Use existing `libs/ui` components where possible (`performance-metrics/` already exists)

**Alternatives considered**:
- Create a completely separate "Family Office Analysis" page: Rejected — spec says P1 is about the portfolio analysis page showing K1 data, not a new page
- Embed an iframe to the family dashboard: Rejected — terrible UX, not a real integration

---

### R-004: How should the default landing page change?

**Decision**: Change the default route from `home` (Overview page) to `family-office` (Family Dashboard).

**Rationale**: The current routing flow is:
- `/**` wildcard → redirects to `home`
- `home` → loads `home-page.routes`, default child renders `GfHomeOverviewComponent` (traditional portfolio overview)

The family dashboard at `/family-office` already exists and renders AUM, allocations, distributions, and K1 status. Making it the default landing page requires only a route redirect change in `app.routes.ts`.

**Alternatives considered**:
- Create a new `/dashboard` route: Rejected — `/family-office` already serves this purpose and has the data bindings
- Modify the home Overview component: Rejected — that component is deeply integrated with the Ghostfolio portfolio model

---

### R-005: What existing UI components can be reused?

**Decision**: Reuse `performance-metrics/`, `distribution-chart/`, `entity-card/`, and other existing `libs/ui` components. Create 2-3 new small components for K1 income summary and nav grouping.

**Rationale**: The `libs/ui` library already contains 35+ components including:
- `performance-metrics/` — displays IRR/TVPI/DPI (already exists, used somewhere)
- `distribution-chart/` — distribution visualization
- `entity-card/` — entity summary card
- `entity-logo/` — entity logo display
- `partnership-table/` — partnership members table
- `k-document-form/` — K1 data entry form
- `benchmark-comparison-chart/` — benchmark overlay
- `value/` — formatted value display with trend indicator
- `toggle/` — month/year toggle (used in analysis page)

**New components needed**:
- `k1-income-summary/` — card showing K1 income categories (ordinary, rental, capital gains, deductions, credits)
- `nav-menu-group/` — toolbar button that triggers a mat-menu dropdown with sub-links (reusable for Partnerships and K-1 Center groups)

**Alternatives considered**:
- Build everything from scratch: Rejected — violates Simplicity First principle
- Use third-party nav component library: Rejected — Angular Material mat-menu is sufficient

---

### R-006: What is the dashboard enhancement strategy?

**Decision**: Enhance the existing family dashboard page to also display portfolio summary metrics (from `fetchPortfolioSummary()`) and K1 income summary (from `fetchActivity()`), making it a comprehensive landing page.

**Rationale**: The current family dashboard only calls `fetchDashboard()` which provides AUM, allocations, distributions, and K1 filing status. But the richer portfolio summary (IRR, TVPI, DPI, RVPI, commitments) and K1 activity data (income decomposition) are available via separate endpoints that have zero consumers. Adding 2-3 more data fetch calls and template sections to the existing dashboard component transforms it from a basic status page into a comprehensive family office command center.

**Dashboard sections (target)**:
1. AUM hero card (existing)
2. Allocation charts (existing: by entity, asset class, structure)
3. **NEW**: Portfolio performance metrics (IRR, TVPI, DPI, RVPI from `fetchPortfolioSummary()`)
4. **NEW**: K1 income summary (current year from `fetchActivity()`)
5. Recent distributions (existing)
6. K-1 filing status (existing)
7. **NEW**: Onboarding guide when no data exists

**Alternatives considered**:
- Create a brand new dashboard component: Rejected — existing one already has most of the infrastructure
- Merge dashboard into home/overview: Rejected — home/overview is tightly coupled to Ghostfolio portfolio model