ghostfolio/specs/003-portfolio-performance-views/data-model.md

Data Model: Portfolio Performance Views

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

Entity Relationship Overview

User ─1:N─► Entity ─1:N─► PartnershipMembership ◄─N:1─ Partnership
                │                                          │
                │                                          ├─1:N─► PartnershipAsset (has assetType)
                │                                          ├─1:N─► PartnershipValuation (has nav, date)
                │                                          └─1:N─► KDocument (has K1Data JSON, taxYear)
                │
                └─1:N─► Distribution (has amount, date, type)

Entities

Entity (existing — no changes)

Field	Type	Description
id	String (UUID)	Primary key
name	String	Display name (e.g., "Entity #1")
type	EntityType enum	INDIVIDUAL, TRUST, LLC, LP, CORPORATION, FOUNDATION, ESTATE
taxId	String?	Tax identification number
userId	String	Owner user FK

Role in feature: Primary grouping dimension for Portfolio Summary view. Each row = one entity.

Partnership (existing — no changes)

Field	Type	Description
id	String (UUID)	Primary key
name	String	Display name (e.g., "Partnership #1")
type	PartnershipType enum	LP, GP, LLC, JOINT_VENTURE, FUND
inceptionDate	DateTime	Used as date for initial contribution cash flow
fiscalYearEnd	String?	Month (e.g., "12" for December)
currency	String	Default "USD"
userId	String	Owner user FK

Role in feature: Contributes to all three views. Asset class determined by its PartnershipAsset records.

PartnershipMembership (existing — no changes)

Field	Type	Description
id	String (UUID)	Primary key
entityId	String	FK → Entity
partnershipId	String	FK → Partnership
ownershipPercent	Decimal	Ownership percentage (0–100)
capitalCommitment	Decimal	Original committed amount
capitalContributed	Decimal	Cumulative contributed to date
classType	String?	Interest class (e.g., "Class A")
effectiveDate	DateTime	Membership start
endDate	DateTime?	Null = active

Role in feature: Links entities to partnerships. Provides Original Commitment and capitalized amounts for Portfolio Summary. Unique constraint: [entityId, partnershipId, effectiveDate].

Distribution (existing — no changes)

Field	Type	Description
id	String (UUID)	Primary key
partnershipId	String?	FK → Partnership
entityId	String	FK → Entity
type	DistributionType enum	INCOME, RETURN_OF_CAPITAL, CAPITAL_GAIN, GUARANTEED_PAYMENT, DIVIDEND, INTEREST
amount	Decimal	Distribution amount
date	DateTime	Distribution date
currency	String	Default "USD"
taxWithheld	Decimal?	Withheld tax amount
notes	String?	Free-text notes

Role in feature: Feeds Distributions column in summaries, cash flow series for XIRR, and per-year distribution totals in Activity view.

PartnershipAsset (existing — no changes)

Field	Type	Description
id	String (UUID)	Primary key
partnershipId	String	FK → Partnership
assetType	FamilyOfficeAssetType enum	PUBLIC_EQUITY, PRIVATE_EQUITY, REAL_ESTATE, HEDGE_FUND, VENTURE_CAPITAL, FIXED_INCOME, COMMODITY, ART_COLLECTIBLE, CRYPTOCURRENCY, CASH, OTHER
name	String	Asset name
currentValue	Decimal	Latest value

Role in feature: Determines which asset class a partnership belongs to (majority assetType). Feeds Asset Class Summary grouping.

PartnershipValuation (existing — no changes)

Field	Type	Description
id	String (UUID)	Primary key
partnershipId	String	FK → Partnership
date	DateTime	Valuation date
nav	Decimal	Net asset value
source	ValuationSource enum	APPRAISAL, MARKET, MANUAL, NAV_STATEMENT, FUND_ADMIN

Role in feature: Provides "Residual Used" (latest NAV × ownership%) for RVPI and TVPI. Terminal value for XIRR cash flows.

KDocument (existing — data JSON schema extended)

Field	Type	Description
id	String (UUID)	Primary key
partnershipId	String	FK → Partnership
type	KDocumentType enum	K1, K3
taxYear	Int	Tax year (e.g., 2024)
filingStatus	KDocumentStatus enum	DRAFT, ESTIMATED, FINAL
data	Json	K1Data or K3Data structured JSON
documentFileId	String?	FK → Document

Unique constraint: [partnershipId, type, taxYear]

Role in feature: Primary data source for Activity view income components and tax basis fields.

K1Data JSON Schema (extended)

Existing fields (no changes)

Field	K-1 Box	Type	Activity Column Mapping
ordinaryIncome	Box 1	number	Part of "Remaining K-1 Income/Ded."
netRentalIncome	Box 2	number	Part of "Remaining K-1 Income/Ded."
otherRentalIncome	Box 3	number	Part of "Remaining K-1 Income/Ded."
guaranteedPayments	Box 4	number	Part of "Remaining K-1 Income/Ded."
interestIncome	Box 5	number	"Interest" column
dividends	Box 6a	number	"Dividends" column
qualifiedDividends	Box 6b	number	(sub-detail of dividends)
royalties	Box 7	number	Part of "Remaining K-1 Income/Ded."
capitalGainLossShortTerm	Box 8	number	Part of "Cap Gains"
capitalGainLossLongTerm	Box 9a	number	Part of "Cap Gains"
unrecaptured1250Gain	Box 9b	number	Part of "Cap Gains"
section1231GainLoss	Box 9c	number	Part of "Cap Gains"
otherIncome	Box 11	number	Part of "Remaining K-1 Income/Ded."
section179Deduction	Box 12	number	Part of "Remaining K-1 Income/Ded." (negative)
otherDeductions	Box 13	number	Part of "Remaining K-1 Income/Ded." (negative)
selfEmploymentEarnings	Box 14	number	Part of "Remaining K-1 Income/Ded."
foreignTaxesPaid	Box 16	number	Part of "Remaining K-1 Income/Ded." (negative)
alternativeMinimumTaxItems	Box 17	number	(informational)
distributionsCash	Box 19a	number	Part of "Distributions"
distributionsProperty	Box 19b	number	Part of "Distributions"

New fields (added for tax basis tracking)

Field	Source	Type	Description
beginningTaxBasis	Prior year ending or manual	number?	Beginning of year tax basis
endingTaxBasis	Computed or manual	number?	End of year tax basis
endingGLBalance	General ledger	number?	Ending GL balance per books
k1CapitalAccount	K-1 Schedule L	number?	Ending K-1 capital account
otherAdjustments	K-1 Box 18c etc.	number?	Other basis adjustments
activityNotes	Manual entry	string?	Per-year notes (e.g., "AJE Completed")

All new fields are optional (?) to maintain backward compatibility with existing K-1 documents.

Derived/Computed Fields

These are computed at query time and not stored:

Summary View Computations (per entity or per asset class)

Metric	Formula	Notes
Original Commitment	Σ membership.capitalCommitment	Across active memberships in scope
Paid-In (ABS)	Σ membership.capitalContributed	Absolute value of contributions
% Called	Paid-In ÷ Original Commitment × 100	Percentage; "N/A" if commitment = 0
Unfunded Commitment	Original Commitment − Paid-In	Can be 0
Distributions	Σ distribution.amount	All distributions in scope
Residual Used	Σ (latestValuation.nav × membership.ownershipPercent / 100)	Per-partnership NAV allocated by ownership
DPI	Distributions ÷ Paid-In	Decimal multiple; 0 if Paid-In = 0
RVPI	Residual Used ÷ Paid-In	Decimal multiple; 0 if Paid-In = 0
TVPI	(Distributions + Residual Used) ÷ Paid-In	Decimal multiple; 0 if Paid-In = 0
IRR (XIRR)	Newton-Raphson on merged cash flows	null → "N/A" if < 2 cash flows

Activity View Computations (per row)

Field	Formula
Capital Gains	shortTerm + longTerm + unrecaptured1250Gain + section1231GainLoss
Remaining K-1 Income/Ded.	ordinaryIncome + netRentalIncome + otherRentalIncome + guaranteedPayments + royalties + otherIncome + selfEmploymentEarnings − section179Deduction − otherDeductions − foreignTaxesPaid
Total Income	Interest + Dividends + Capital Gains + Remaining K-1 Income/Ded.
Book-to-Tax Adj	endingGLBalance − endingTaxBasis
K-1 Capital vs Tax Basis Diff	k1CapitalAccount − endingTaxBasis
Excess Distribution	max(0, Distributions − (beginningTaxBasis + Contributions + Total Income + otherAdjustments))
Negative Basis?	endingTaxBasis < 0 → "YES"
Δ Ending Basis vs Prior Year	endingTaxBasis − beginningTaxBasis

State Transitions

KDocument Filing Status

DRAFT → ESTIMATED → FINAL

Each transition may update the K1Data values (including the new tax basis fields). The Activity view always shows the latest data regardless of filing status.

Validation Rules

Rule	Scope	Description
capitalCommitment ≥ 0	PartnershipMembership	Commitment cannot be negative
capitalContributed ≥ 0	PartnershipMembership	Contributed cannot be negative
capitalContributed ≤ capitalCommitment	PartnershipMembership	Cannot contribute more than committed
ownershipPercent ∈ (0, 100]	PartnershipMembership	Must be positive percentage
distribution.amount > 0	Distribution	Distributions are positive flows
taxYear ∈ [1900, current+1]	KDocument	Reasonable year range
nav ≥ 0	PartnershipValuation	NAV cannot be negative
Σ ownershipPercent per partnership ≤ 100	PartnershipMembership	Total ownership cannot exceed 100%

FamilyOfficeAssetType → Display Label Mapping

Enum Value	Display Label
REAL_ESTATE	Real Estate
VENTURE_CAPITAL	Venture Capital
PRIVATE_EQUITY	Private Equity
HEDGE_FUND	Hedge Fund
FIXED_INCOME	Credit
COMMODITY	Natural Resources
OTHER	Other
PUBLIC_EQUITY	Public Equity
ART_COLLECTIBLE	Art & Collectibles
CRYPTOCURRENCY	Cryptocurrency
CASH	Cash

Note: "Co-Investment" and "Infrastructure" from the spec map to PRIVATE_EQUITY and OTHER respectively until dedicated enum values are added.