ghostfolio/specs/003-portfolio-performance-views/research.md

Research: Portfolio Performance Views

Feature: 003-portfolio-performance-views Date: 2026-03-16

Decision Log

R-001: XIRR Aggregation Strategy

Decision: Reuse existing FamilyOfficePerformanceCalculator.computeXIRR() with concatenated cash flows for entity-level and asset-class-level aggregation.

Rationale: The CashFlow interface is { amount: number, date: Date } with no partnership identifier — cash flows from multiple partnerships can be freely merged into a single array. The calculator already handles sorting by date and Newton-Raphson iteration. For entity-level XIRR, collect all cash flows across the entity's partnerships (scaled by ownershipPercent), add a terminal NAV entry, and pass to computeXIRR(). For asset-class-level XIRR, group partnerships by their dominant FamilyOfficeAssetType and do the same.

Alternatives considered:

• Weighted average of per-partnership IRRs — rejected because IRR is not linearly composable; time-weighting doesn't produce a correct aggregate.
• New calculator class — rejected because the existing one handles the computation correctly with no modification needed.

R-002: Asset Class Determination for Partnerships

Decision: Determine a partnership's asset class from the majority FamilyOfficeAssetType of its PartnershipAsset records. If no assets exist, default to OTHER.

Rationale: The PartnershipAsset.assetType field is already populated per the existing data model. Most partnerships have a dominant asset type. The spec's asset class categories (Real Estate, Venture Capital, Private Equity, Hedge Fund, Credit, Co-Investment, Infrastructure, Natural Resources, Other) map to FamilyOfficeAssetType enum values.

Mapping from spec categories to existing enum:

Spec Category	FamilyOfficeAssetType	Notes
Real Estate	REAL_ESTATE	Direct match
Venture Capital	VENTURE_CAPITAL	Direct match
Private Equity	PRIVATE_EQUITY	Direct match
Hedge Fund	HEDGE_FUND	Direct match
Credit	FIXED_INCOME	Closest existing match
Co-Investment	PRIVATE_EQUITY	Co-investments are typically PE deals
Infrastructure	OTHER	No dedicated enum value; consider adding INFRASTRUCTURE
Natural Resources	COMMODITY	Closest existing match
Other	OTHER	Direct match

Alternatives considered:

• Adding new enum values (INFRASTRUCTURE, CO_INVESTMENT, CREDIT, NATURAL_RESOURCES) — viable but requires Prisma migration and enum update; can be a Phase 2 enhancement.
• Using Partnership.type instead of asset-level classification — rejected because PartnershipType (LP, GP, LLC, etc.) is structure-based, not asset-class-based.

R-003: Tax Basis & Activity Data Architecture

Decision: Extend KDocument.data JSON schema with additional fields for tax basis tracking, and compute derived fields at query time.

Rationale: The existing K1Data interface stores K-1 box values (interest, dividends, capital gains, deductions, distributions) but lacks tax basis and GL balance fields. The Activity view needs: Beginning Basis, Ending Tax Basis, Ending GL Balance Per Books, K-1 Capital Account, and Other Adjustments. These are typically manually entered from K-1 Schedule L and the firm's general ledger — they are not derivable from existing data.

Storage approach: Extend the K1Data interface with optional fields:

• beginningBasis: number (prior year ending basis, can be auto-populated from previous year's ending)
• endingTaxBasis: number (computed or manually entered)
• endingGLBalance: number (from GL, manually entered)
• k1CapitalAccount: number (from K-1 Schedule L, manually entered)
• otherAdjustments: number (IRS form Box 18c or similar adjustments)
• notes: string (e.g., "AJE Completed")

Fields derived at query time (no storage needed):

• totalIncome = interest + dividends + capitalGains + remainingK1IncomeDed
• bookToTaxAdj = endingGLBalance − endingTaxBasis
• k1CapitalVsTaxBasisDiff = k1CapitalAccount − endingTaxBasis
• excessDistribution = max(0, distributions − (beginningBasis + contributions + totalIncome))
• negativeBasis = endingTaxBasis < 0
• deltaEndingBasis = endingTaxBasis − beginningBasis (from prior year)

Alternatives considered:

• New TaxBasisRecord model — rejected to avoid schema migration complexity; the JSON column is already flexible and the data is naturally part of the K-1 document context.
• Pure computation from existing data — rejected because GL balance and K-1 capital account are external inputs not derivable from existing fields.

R-004: Page Architecture — New Page vs. Repurpose

Decision: Create a new /portfolio-views page with three Material tabs, accessible from main navigation.

Rationale: The existing pages serve different purposes:

• /home — Ghostfolio's original portfolio overview (public market holdings)
• /family-office — High-level dashboard (AUM, allocations, recent distributions)
• /reports — Period-specific reporting with benchmarks
• /portfolio — Ghostfolio analysis (allocations, FIRE, X-Ray)

None of these naturally accommodate three wide data tables. The new page provides a dedicated analytical workspace matching the CSV-based views the user needs. Tab-based navigation between the three views keeps them co-located.

Alternatives considered:

• Repurpose /family-office dashboard — rejected because the dashboard serves a different purpose (at-a-glance summary) and would become cluttered.
• Add tabs to /reports — rejected because reports are period/benchmark-focused while these views are standing data tables.
• Repurpose /home overview — rejected because /home is the original Ghostfolio functionality.

R-005: Accounting Number Format

Decision: Use a shared Angular pipe for accounting-format numbers: comma separators, parentheses for negatives, dashes for zero.

Rationale: The CSV attachments show consistent formatting: "1,000,000" for positive, "(355,885)" for negative, "-" for zero. A custom pipe (or extending an existing one) keeps formatting consistent across all three views and is reusable for future features.

Alternatives considered:

• Inline formatting in each component — rejected due to duplication.
• Using Angular's built-in CurrencyPipe — rejected because it uses minus signs (not parentheses) and doesn't support the dash-for-zero convention.

R-006: Valuation Year Filter

Decision: Implement as a year dropdown at the page level, defaulting to current year. Filters data for Portfolio Summary and Asset Class Summary to valuations/distributions through year-end. Activity view uses year as a row filter.

Rationale: The CSV references "Valuation Year from IRR Helper!B2" — this is a single global parameter that controls which year-end data the summaries use. Implementing at the page level means one filter controls all three tabs, matching the spreadsheet behavior.

Alternatives considered:

• Per-tab year filters — rejected for complexity and divergence from the spreadsheet model.
• No year filter (always latest) — rejected because the spec explicitly requires it (FR-006).

R-007: Activity View Data Source

Decision: Build activity rows by joining PartnershipMembership, Distribution, and KDocument data per entity-partnership-year combination.

Rationale: The Activity CSV has one row per entity-partnership-year with data from three sources:

1. Contributions from PartnershipMembership.capitalContributed (need year attribution — may need to track per-year contributions)
2. Income components from KDocument.data (K1Data fields, keyed by partnershipId + taxYear)
3. Distributions from Distribution model (summed per entity-partnership-year)
4. Tax basis fields from extended KDocument.data (R-003)

The join key is (entityId, partnershipId, taxYear) — entities derive from memberships, partnerships from the membership relation, and years from K-documents and distributions.

Alternatives considered:

• Separate ActivityRecord model — rejected as it would duplicate data already stored across existing models.
• Client-side aggregation — rejected because the data volume and computation complexity are better handled server-side.

R-008: Contribution Year Attribution

Decision: Use Distribution records of type contributions (capital calls) for year-attributed contributions. Fall back to PartnershipMembership.capitalContributed as the total when per-year breakdown is unavailable.

Rationale: The Activity CSV shows contributions per year (e.g., $1,000,000 in year 1, $131,566 in a later year). PartnershipMembership.capitalContributed stores only the cumulative total. The Distribution model already supports negative-amount (or capital-call type) records with dates. If per-year data exists, use it; otherwise attribute the full capitalContributed to the membership's effectiveDate year.

Alternatives considered:

• New CapitalCall model — rejected; the Distribution model can represent both inflows and outflows with type differentiation.
• Manually entered per-year breakdown — possible but adds user burden; better to derive from existing dated records.