ghostfolio/specs/001-family-office-transform/data-model.md

Data Model: Single Family Office Platform

Phase 1 Output | Date: 2026-03-15

Overview

This document defines 9 new Prisma models and 8 new enums that extend the existing Ghostfolio schema. The design adds an entity/ownership layer above the existing User → Account → Order hierarchy, plus partnership, distribution, K-document, and document management.

Entity Relationship Diagram (Conceptual)

User (existing)
 ├── Entity[] ─────────────┬── Ownership[] ──── Account (existing, composite PK)
 │   (trust, LLC, etc.)    ├── PartnershipMembership[] ──── Partnership
 │                         ├── Distribution[] (received)     ├── PartnershipMembership[]
 │                         └── Document[]                    ├── PartnershipAsset[] ── AssetValuation[]
 │                                                           ├── PartnershipValuation[]
 │                                                           ├── Distribution[] (paid)
 │                                                           ├── KDocument[]
 │                                                           └── Document[]
 └── Account[] (existing, unchanged)
      └── Order[] (existing, unchanged)

New Enums

EntityType

Represents the legal structure of a family office entity.

Value	Description
INDIVIDUAL	Natural person
TRUST	Revocable or irrevocable trust
LLC	Limited liability company
LP	Limited partnership (entity acting as an LP)
CORPORATION	C-Corp or S-Corp
FOUNDATION	Private foundation
ESTATE	Estate of a deceased individual

PartnershipType

Represents the legal structure of an investment partnership.

Value	Description
LP	Limited partnership
GP	General partnership
LLC	Limited liability company (operating as partnership)
JOINT_VENTURE	Joint venture
FUND	Investment fund (hedge fund, PE fund, etc.)

DistributionType

Categorizes cash flows from partnerships to entities.

Value	Description
INCOME	Ordinary income distribution
RETURN_OF_CAPITAL	Return of contributed capital
CAPITAL_GAIN	Capital gain distribution
GUARANTEED_PAYMENT	Guaranteed payment to partner
DIVIDEND	Dividend distribution
INTEREST	Interest income distribution

KDocumentType

Type of tax document.

Value	Description
K1	Schedule K-1 (Form 1065)
K3	Schedule K-3 (international)

KDocumentStatus

Filing lifecycle of a K-document.

Value	Description
DRAFT	Initial entry, not yet received from fund
ESTIMATED	Estimated figures, pre-final K-1
FINAL	Final K-1 received and verified

FamilyOfficeAssetType

Asset classes for partnership-held assets.

Value	Description
PUBLIC_EQUITY	Publicly traded stocks/ETFs
PRIVATE_EQUITY	Private company investments
REAL_ESTATE	Real property
HEDGE_FUND	Hedge fund allocation
VENTURE_CAPITAL	VC fund allocation
FIXED_INCOME	Bonds, notes, fixed income
COMMODITY	Physical commodities
ART_COLLECTIBLE	Art, wine, collectibles
CRYPTOCURRENCY	Digital assets
CASH	Cash and equivalents
OTHER	Uncategorized

ValuationSource

How a valuation was determined.

Value	Description
APPRAISAL	Third-party appraisal
MARKET	Market-based pricing
MANUAL	Manual entry by administrator
NAV_STATEMENT	Fund administrator NAV statement
FUND_ADMIN	Fund administrator report

DocumentType

Categories for uploaded documents.

Value	Description
K1	K-1 tax document PDF
K3	K-3 tax document PDF
CAPITAL_CALL	Capital call notice
DISTRIBUTION_NOTICE	Distribution notice
NAV_STATEMENT	NAV statement
APPRAISAL	Appraisal report
TAX_RETURN	Tax return
SUBSCRIPTION_AGREEMENT	Subscription/partnership agreement
OTHER	Other document

New Models

Entity

A legal person or structure that can own assets and be a member of partnerships.

Field	Type	Constraints	Description
id	String	PK, UUID, auto-generated	Unique identifier
name	String	Required, indexed	Entity display name
type	EntityType	Required, indexed	Legal structure type
taxId	String?	Optional	Tax identification number (EIN, SSN)
createdAt	DateTime	Default: now()	Creation timestamp
updatedAt	DateTime	Auto-updated	Last modification timestamp
userId	String	FK → User.id, indexed	Administering user

Relations:

• user → User (many-to-one, cascade delete)
• ownerships ← Ownership[] (one-to-many)
• memberships ← PartnershipMembership[] (one-to-many)
• distributionsReceived ← Distribution[] (one-to-many)
• documents ← Document[] (one-to-many)

Partnership

An investment vehicle or legal structure that holds assets and has members.

Field	Type	Constraints	Description
id	String	PK, UUID, auto-generated	Unique identifier
name	String	Required, indexed	Partnership display name
type	PartnershipType	Required, indexed	Legal structure type
inceptionDate	DateTime	Required	Date partnership was formed
fiscalYearEnd	Int	Default: 12	Month number (1-12) of fiscal year end
currency	String	Required	Base currency for NAV reporting
createdAt	DateTime	Default: now()	Creation timestamp
updatedAt	DateTime	Auto-updated	Last modification timestamp
userId	String	FK → User.id, indexed	Administering user

Relations:

• user → User (many-to-one, cascade delete)
• members ← PartnershipMembership[] (one-to-many)
• assets ← PartnershipAsset[] (one-to-many)
• valuations ← PartnershipValuation[] (one-to-many)
• distributions ← Distribution[] (one-to-many)
• kDocuments ← KDocument[] (one-to-many)
• documents ← Document[] (one-to-many)

PartnershipMembership

The relationship between an entity and a partnership with ownership details.

Field	Type	Constraints	Description
id	String	PK, UUID, auto-generated	Unique identifier
entityId	String	FK → Entity.id, indexed	Member entity
partnershipId	String	FK → Partnership.id, indexed	Partnership
ownershipPercent	Decimal	Required	Ownership percentage (0-100)
capitalCommitment	Decimal?	Optional	Total capital committed
capitalContributed	Decimal?	Optional	Capital contributed to date
classType	String?	Optional	Class designation (e.g., "Class A LP", "GP Interest")
effectiveDate	DateTime	Required	Date this membership/percentage took effect
endDate	DateTime?	Optional	Date membership ended (null = active)
createdAt	DateTime	Default: now()	Creation timestamp
updatedAt	DateTime	Auto-updated	Last modification timestamp

Relations:

• entity → Entity (many-to-one, cascade delete)
• partnership → Partnership (many-to-one, cascade delete)

Unique constraint: @@unique([entityId, partnershipId, effectiveDate]) — prevents duplicate membership records for the same entity-partnership on the same date.

Ownership

The relationship between an entity and a directly-owned account.

Field	Type	Constraints	Description
id	String	PK, UUID, auto-generated	Unique identifier
entityId	String	FK → Entity.id, indexed	Owning entity
accountId	String	FK (composite) → Account.id	Owned account
accountUserId	String	FK (composite) → Account.userId	Account's user
ownershipPercent	Decimal	Required	Ownership percentage (0-100)
acquisitionDate	DateTime?	Optional	Date ownership was acquired
costBasis	Decimal?	Optional	Cost basis of ownership stake
effectiveDate	DateTime	Required	Date this ownership took effect
endDate	DateTime?	Optional	Date ownership ended (null = active)
createdAt	DateTime	Default: now()	Creation timestamp
updatedAt	DateTime	Auto-updated	Last modification timestamp

Relations:

• entity → Entity (many-to-one, cascade delete)
• account → Account (many-to-one, cascade delete, composite FK on [accountId, accountUserId])

Unique constraint: @@unique([entityId, accountId, accountUserId, effectiveDate]) — prevents duplicate ownership records for the same entity-account on the same date.

Distribution

A cash flow from a partnership or investment to a receiving entity.

Field	Type	Constraints	Description
id	String	PK, UUID, auto-generated	Unique identifier
partnershipId	String?	FK → Partnership.id, optional, indexed	Source partnership
entityId	String	FK → Entity.id, indexed	Receiving entity
type	DistributionType	Required	Distribution category
amount	Decimal	Required	Distribution amount
date	DateTime	Required, indexed	Distribution date
currency	String	Required	Currency of distribution
taxWithheld	Decimal?	Default: 0	Tax withheld at source
notes	String?	Optional	Free-text notes
createdAt	DateTime	Default: now()	Creation timestamp
updatedAt	DateTime	Auto-updated	Last modification timestamp

Relations:

• partnership → Partnership? (many-to-one, optional, cascade delete)
• entity → Entity (many-to-one, cascade delete)

KDocument

Structured K-1 or K-3 tax document data for a partnership tax year.

Field	Type	Constraints	Description
id	String	PK, UUID, auto-generated	Unique identifier
partnershipId	String	FK → Partnership.id, indexed	Associated partnership
type	KDocumentType	Required	K-1 or K-3
taxYear	Int	Required, indexed	Tax year (e.g., 2025)
filingStatus	KDocumentStatus	Default: DRAFT	Current filing status
data	Json	Required	Structured K-1/K-3 box data (see K1Data interface)
documentFileId	String?	FK → Document.id, optional	Linked uploaded PDF
createdAt	DateTime	Default: now()	Creation timestamp
updatedAt	DateTime	Auto-updated	Last modification timestamp

Relations:

• partnership → Partnership (many-to-one, cascade delete)
• documentFile → Document? (many-to-one, optional)

Unique constraint: @@unique([partnershipId, type, taxYear]) — one K-1 and one K-3 per partnership per tax year.

PartnershipAsset

An underlying asset held within a partnership.

Field	Type	Constraints	Description
id	String	PK, UUID, auto-generated	Unique identifier
partnershipId	String	FK → Partnership.id, indexed	Owning partnership
assetType	FamilyOfficeAssetType	Required, indexed	Asset class
name	String	Required	Asset display name
description	String?	Optional	Detailed description
acquisitionDate	DateTime?	Optional	Date acquired
acquisitionCost	Decimal?	Optional	Cost at acquisition
currentValue	Decimal?	Optional	Latest known value
currency	String	Required	Asset currency
metadata	Json?	Optional	Flexible metadata (address for real estate, etc.)
createdAt	DateTime	Default: now()	Creation timestamp
updatedAt	DateTime	Auto-updated	Last modification timestamp

Relations:

• partnership → Partnership (many-to-one, cascade delete)
• valuations ← AssetValuation[] (one-to-many)

AssetValuation

A point-in-time value assessment of a partnership asset.

Field	Type	Constraints	Description
id	String	PK, UUID, auto-generated	Unique identifier
partnershipAssetId	String	FK → PartnershipAsset.id, indexed	Valued asset
date	DateTime	Required, indexed	Valuation date
value	Decimal	Required	Assessed value
source	ValuationSource	Required	How value was determined
notes	String?	Optional	Valuation notes
createdAt	DateTime	Default: now()	Creation timestamp
updatedAt	DateTime	Auto-updated	Last modification timestamp

Relations:

• partnershipAsset → PartnershipAsset (many-to-one, cascade delete)

Unique constraint: @@unique([partnershipAssetId, date]) — one valuation per asset per date.

PartnershipValuation

A point-in-time NAV for an entire partnership.

Field	Type	Constraints	Description
id	String	PK, UUID, auto-generated	Unique identifier
partnershipId	String	FK → Partnership.id, indexed	Valued partnership
date	DateTime	Required, indexed	Valuation date
nav	Decimal	Required	Net Asset Value
source	ValuationSource	Required	How NAV was determined
notes	String?	Optional	Valuation notes
createdAt	DateTime	Default: now()	Creation timestamp
updatedAt	DateTime	Auto-updated	Last modification timestamp

Relations:

• partnership → Partnership (many-to-one, cascade delete)

Unique constraint: @@unique([partnershipId, date]) — one NAV per partnership per date.

Document

A file (PDF, etc.) associated with an entity, partnership, or K-document.

Field	Type	Constraints	Description
id	String	PK, UUID, auto-generated	Unique identifier
entityId	String?	FK → Entity.id, optional, indexed	Associated entity
partnershipId	String?	FK → Partnership.id, optional, indexed	Associated partnership
type	DocumentType	Required	Document category
name	String	Required	Display name / filename
filePath	String	Required	Filesystem path to file
fileSize	Int?	Optional	File size in bytes
mimeType	String?	Optional	MIME type (e.g., application/pdf)
taxYear	Int?	Optional	Associated tax year
createdAt	DateTime	Default: now()	Creation timestamp
updatedAt	DateTime	Auto-updated	Last modification timestamp

Relations:

• entity → Entity? (many-to-one, optional, cascade delete)
• partnership → Partnership? (many-to-one, optional, cascade delete)
• kDocuments ← KDocument[] (one-to-many, back-reference)

Modifications to Existing Models

Account (existing)

Add one optional back-reference — no column changes, no migration impact on existing data:

New Field	Type	Description
ownerships	Ownership[]	Back-reference to ownership records

User (existing)

Add two optional back-references — no column changes, no migration impact:

New Field	Type	Description
entities	Entity[]	Entities administered by this user
partnerships	Partnership[]	Partnerships administered by this user

Application-Layer Types

K1Data (TypeScript interface, stored as JSON)

interface K1Data {
  ordinaryIncome: number; // Box 1
  netRentalIncome: number; // Box 2
  otherRentalIncome: number; // Box 3
  guaranteedPayments: number; // Box 4
  interestIncome: number; // Box 5
  dividends: number; // Box 6a
  qualifiedDividends: number; // Box 6b
  royalties: number; // Box 7
  capitalGainLossShortTerm: number; // Box 8
  capitalGainLossLongTerm: number; // Box 9a
  unrecaptured1250Gain: number; // Box 9b
  section1231GainLoss: number; // Box 9c
  otherIncome: number; // Box 11
  section179Deduction: number; // Box 12
  otherDeductions: number; // Box 13
  selfEmploymentEarnings: number; // Box 14
  foreignTaxesPaid: number; // Box 16
  alternativeMinimumTaxItems: number; // Box 17
  distributionsCash: number; // Box 19a
  distributionsProperty: number; // Box 19b
}

Validation Rules

1. Ownership percentage: 0 < ownershipPercent <= 100. Sum of active ownership percentages for a single account must not exceed 100.
2. Partnership membership percentage: 0 < ownershipPercent <= 100. Sum of active membership percentages for a single partnership must not exceed 100.
3. Distribution date: Must be >= partnership inception date.
4. K-document tax year: Must be >= year of partnership inception date.
5. Partnership fiscal year end: Must be 1-12.
6. Entity deletion: Blocked if entity has any active ownerships or memberships (endDate is null).
7. Partnership deletion: Cascades to all memberships, assets, valuations, distributions, K-documents, and documents.