portfolio-hub/docs/data-model.md

# Portfolio Hub Data Model

- Baseline Mode: observed
- Baseline Seed: .stagepilot/bootstrap/baseline.yaml
- Status: confirmed
- Owner: repository-maintainers
- Last Updated (KST): 2026-05-13 00:00
- Source Discovery / Batch: bootstrap-baseline, bat-001, bat-006, bat-008, bat-010

## Project Summary
- PortfolioHub exposes portfolio management and trading ledger workflows through a FastAPI service and a companion CLI.

## Primary Domain
- Portfolio management and trading ledger services.

## Primary Persistence Backend
- PostgreSQL or TimescaleDB via psycopg with Alembic-managed migrations.

## Purpose
- This document captures the approved cross-cutting data model baseline for the project.
- It is a shared reference for REQ drafting, batch design, implementation, verification, migration planning, and handoff.

## Scope
- Covers core entities, relationships, states, persistence mappings, and shared consistency rules.
- Does not duplicate full functional acceptance criteria already owned by REQ documents.
- Does not replace ORM definitions, migration files, or generated schema artifacts.

## Model Summary

- Portfolio :: owned investment portfolio with balances, strategy references, tags, comments, and ledger history
- User :: authenticated principal that owns portfolios and receives client or service tokens
- Daemon :: stable logical identity for a trading daemon process; registered per user; bound to service tokens and assigned to assets
- AuthToken :: issued client or service token with permission, runtime_id, and optional daemon_id binding
- BrokerCredential :: encrypted broker API credentials per user-broker pair
- LedgerTrade :: idempotent trade execution record keyed by (asset_id, order_id, execution_id)
- Asset :: catalog entry representing a tradeable asset; portfolios reference assets via FK

## Entity: `Asset`

- Purpose: represent a tradeable asset in the catalog; serves as FK anchor for portfolios
- Source of Truth: assets table; managed exclusively via admin CLI / admin API
- Lifecycle: created → optionally deactivated; never deleted (portfolios reference it with RESTRICT FK)

### Key Fields

- asset_id :: uuid :: server-generated UUID primary key (gen_random_uuid())
- symbol :: text UNIQUE :: exchange symbol (e.g. 005930, BTC)
- markets :: text[] :: array of market codes the asset is listed on (e.g. ["KRX", "NASDAQ"])
- display_name :: text|null :: human-readable name for display
- status :: text :: "active" | "inactive"; only active assets can be referenced by new portfolios

### Uniqueness Constraints

- assets_symbol_key :: UNIQUE (symbol) :: one catalog entry per symbol

### Indexes

- idx_assets_markets_gin :: GIN index on markets array :: supports efficient array containment queries

### Relationships

- Portfolio :: portfolios.asset_id FK → assets.asset_id ON DELETE RESTRICT; one asset → many portfolios

### State Rules

- Only `status="active"` assets can be referenced when creating a new portfolio.
- Deactivated assets do not affect existing portfolios; only new creation is blocked.

## Entity: `Portfolio`

- Purpose: represent an owned investment portfolio with balances, strategy references, tags, comments, and trading history
- Source of Truth: portfolios table with dependent portfolio_ledger, portfolio_comments, and portfolio_tags tables
- Lifecycle: created -> updated by trade and cash operations -> reset or deleted

### Key Fields

- portfolio_id :: uuid :: server-generated UUID primary key; assigned at creation and never changed; BAT-006 migrated all pre-existing TEXT portfolio_id values to UUIDs
- name :: text :: human-readable portfolio name; unique per owner_user_id; validated against [a-zA-Z0-9._:-]{1,100}
- asset_id :: uuid :: FK → assets.asset_id; catalog reference for the traded asset; BAT-001 migrated symbol/market columns to this FK
- symbol :: text :: display symbol populated via JOIN on assets (read-only, not stored in portfolios)
- owner_user_id :: text|null :: owning user reference for attribution and authorization
- active_strategy_id :: text|null :: currently selected strategy-set reference
- cash_balance :: double precision :: current cash snapshot after the latest ledger event
- asset_quantity :: double precision :: current holdings snapshot after the latest ledger event
- managed_by_daemon_id :: text|null :: soft reference to daemons.id; controls daemon-scoped API access; NULL = unassigned (fail-closed for ledger writes and asset listing); added by migration 20260513_0016

### Uniqueness Constraints

- uq_portfolios_owner_name :: UNIQUE (owner_user_id, name) :: enforces per-user portfolio name uniqueness at the DB level

### Relationships

- Asset :: asset_id FK ties each portfolio to exactly one catalog asset
- User :: owner_user_id links a portfolio to its owning user when ownership is assigned
- Daemon :: managed_by_daemon_id links a portfolio to exactly one daemon; NULL means unassigned
- StrategySet :: active_strategy_id and avabile_strategies connect reusable strategy definitions
- LedgerEntry, PortfolioComment, PortfolioTag :: child records are keyed by portfolio_id (UUID)

### State Rules

- Portfolio names are required, must be unique per owner_user_id, and are validated at the schema layer before persistence.
- portfolio_id is server-generated at creation; clients must never supply or assume a specific portfolio_id value.
- Balance-changing commands must update snapshot fields and append a ledger row together.
- Tags are unique per portfolio and comments are retrieved in created_at descending order.

## Entity: `User`

- Purpose: represent an authenticated principal that can own portfolios and receive client or service tokens
- Source of Truth: users table with dependent auth_tokens rows
- Lifecycle: bootstrapped or created -> updated -> deactivated or deleted

### Key Fields

- id :: text :: stable user primary key
- username :: text :: unique login and CLI lookup key
- email :: text|null :: unique contact identity when present
- permission :: text :: baseline role of read, trade-write, or admin
- is_active :: boolean :: authentication and authorization gate
- last_login_at :: timestamptz|null :: latest successful login timestamp

### Relationships

- AuthToken :: user_id links issued client and service tokens to the owning user
- Portfolio :: portfolios.owner_user_id ties portfolios to a managing user
- TokenPrincipal :: runtime auth resolution derives principals from persisted tokens and users

### State Rules

- username and email remain unique identifiers when present.
- Bootstrap admin creation only runs when the users table is empty and DB mode is enabled.
- Permission changes affect both API guards and CLI mutation capabilities.

## Entity: `AuthToken`

- Purpose: represent an issued client or service token linked to a user with permission and optional runtime identifier
- Source of Truth: auth_tokens table
- Lifecycle: issued -> optionally rotated -> revoked or expired

### Key Fields

- id :: text :: primary key; raw token value (stored hashed in practice)
- user_id :: text :: owning user reference
- token_type :: text :: "client" or "service"
- token_source :: text :: "db" for persisted tokens; "env" for environment-injected tokens
- permission :: text :: read, trade-write, or admin
- service_name :: text|null :: logical name for service tokens (unique within token_type="service")
- runtime_id :: text|null :: per-token opaque runtime identifier; regenerated on every rotate; added by migration 20260502_0014
- daemon_id :: text|null :: soft reference to daemons.id; stable across rotates (rotate invariant); NULL = legacy/unbound token (fail-closed for daemon-scoped endpoints); added by migration 20260513_0016
- expires_at :: timestamptz|null :: token expiry; null for non-expiring tokens
- created_at :: timestamptz :: issuance timestamp

### Uniqueness Constraints

- idx_auth_tokens_service_name_unique :: UNIQUE (service_name) WHERE token_type='service'
- idx_auth_tokens_runtime_id_unique :: UNIQUE (runtime_id) WHERE runtime_id IS NOT NULL

### State Rules

- Service tokens are the only tokens accepted by v1 API endpoints.
- runtime_id is per-token and changes on every rotate; daemon_id is stable across rotates (daemon_id invariant).
- daemon_id=NULL tokens are fail-closed on GET /v1/assets and POST /v1/assets/{asset_id}/ledger/trades (HTTP 403); GET /v1/user_info returns 200 + `daemon_id: null` as diagnostic.
- Token permission gates both HTTP API guards and CLI mutation capabilities.

## Entity: `Daemon`

- Purpose: represent a stable logical identity for a trading daemon process; registered per user; bound to service tokens at issuance; assigned to assets
- Source of Truth: daemons table (added by migration 20260513_0016)
- Lifecycle: created by operator via `pfhub daemon create` -> optionally updated -> deactivated

### Key Fields

- id :: text :: server-generated UUID primary key; stable logical identity across service-token rotates
- owner_user_id :: text :: owning user reference (part of composite unique constraint)
- daemon_slug :: text :: operator-assigned short identifier; unique per owner_user_id
- display_name :: text|null :: human-readable label for the daemon
- is_active :: boolean :: if false, service-token issuance for this daemon is rejected; default true
- created_at :: timestamptz :: registration timestamp
- updated_at :: timestamptz :: last update timestamp

### Uniqueness Constraints

- uq_daemons_owner_slug :: UNIQUE (owner_user_id, daemon_slug) :: one slug per user

### Relationships

- User :: owner_user_id links a daemon to its owning user
- AuthToken :: auth_tokens.daemon_id binds a service token to this daemon (1 token : 1 daemon)
- Portfolio :: portfolios.managed_by_daemon_id assigns an asset to this daemon (1 asset : 1 daemon)

### State Rules

- A daemon must exist and be active before a service token can be bound to it at issuance.
- Deactivating a daemon (is_active=false) blocks new token issuance but does not revoke existing tokens.
- daemon_slug is immutable after creation; only display_name and is_active can be updated.

## Entity: `BrokerCredential`

- Purpose: store Fernet-encrypted broker API credentials per user-broker pair for the trex-basic integration
- Source of Truth: broker_credentials table (added by migration 20260502_0014)
- Lifecycle: upserted via CLI credential command -> optionally rotated

### Key Fields

- user_id :: text :: owning user reference (part of composite PK)
- broker :: text :: broker identifier, e.g., "KIS" (part of composite PK)
- account_ref :: text :: broker account reference or alias
- encrypted_payload :: text :: Fernet-encrypted JSON ciphertext; plaintext is `{"app_key": ..., "app_secret": ...}`; decrypted at query time using CREDENTIAL_ENCRYPTION_KEY (REQ-010)
- credential_version :: integer :: monotonically increasing rotation counter; server_default=1
- last_rotated_at :: timestamptz :: last credential upsert or rotation timestamp; server_default=NOW()

### Uniqueness Constraints

- PRIMARY KEY (user_id, broker) :: one credential entry per user per broker

### State Rules

- encrypted_payload must never contain plaintext credentials; Fernet encryption is mandatory before persistence.
- Decryption failures (wrong key, corrupted payload) log a warning and return `credential_payload: null` in GET /v1/user_info.

## Entity: `LedgerTrade`

- Purpose: record idempotent trade execution entries submitted by trex-basic via POST /v1/assets/{asset_id}/ledger/trades
- Source of Truth: ledger_trades table (added by migration 20260502_0014)
- Lifecycle: inserted once per unique (asset_id, order_id, execution_id) tuple; never updated or deleted

### Key Fields

- ledger_entry_id :: bigint (Identity) :: auto-generated sequential primary key
- asset_id :: text :: portfolio_id (UUID-format text after BAT-006) referencing the trading portfolio
- order_id :: text :: broker-assigned order identifier
- execution_id :: text :: broker-assigned execution/fill identifier
- side :: text :: "buy" or "sell"
- quantity :: numeric(20,8) :: executed quantity
- price :: numeric(20,8) :: execution price
- fee_amount :: numeric(20,8) :: brokerage fee; server_default=0
- tax_amount :: numeric(20,8) :: transaction tax; server_default=0
- executed_at :: timestamptz :: broker-reported execution timestamp
- recorded_at :: timestamptz :: insertion timestamp; server_default=NOW()

### Uniqueness Constraints

- uq_ledger_trades_idempotency :: UNIQUE (asset_id, order_id, execution_id) :: idempotency guarantee; duplicate inserts are detected and return HTTP 200 + status="duplicate"
- idx_ledger_trades_asset_executed :: INDEX (asset_id, executed_at) :: time-range query optimization

### State Rules

- Rows are immutable after insertion; no UPDATE path exists.
- Payload conflict detection: if unique key matches but payload differs → HTTP 409 Conflict.
- asset_id is TEXT (not a FK) but must correspond to a valid portfolios.portfolio_id before insertion.

## Shared Consistency Rules

- auth_tokens.user_id and portfolios.owner_user_id should resolve to existing users before protected flows run.
- strategy_sets.name plus config, strategy_sets.nick, and service token names have uniqueness constraints.
- Portfolio snapshot fields and portfolio_ledger history must stay synchronized across mutations.
- (owner_user_id, name) uniqueness is enforced at both the DB constraint level and the application layer; violations surface as a 409 Conflict or ValueError with a Korean message.

## Persistence / Integration Notes

- Alembic revisions in migrations/versions/ are the ordered schema history for persistent environments.
- app/repositories/postgres.py includes ensure_schema() for bootstrap safety, but long-term schema evolution should run through Alembic.
- Comments, tags, auth tokens, and ledger rows are normalized into dedicated tables keyed to users or portfolios.

## Current Gaps / Planned Changes

- Production-like migration verification against a real PostgreSQL or TimescaleDB instance is still pending.
- Retention and archival rules are not yet documented for ledger, comment, or revoked-token records.
- Future authorization changes may require stronger ownership constraints in schema or query paths.

## Update Triggers

- Update this document when a core entity, key field, or relationship changes.
- Update this document when lifecycle or persistence behavior changes.
- Update this document when a batch introduces a migration, backfill, or breaking data assumption.

## Change Log

- 2026-05-19 KST: bat-002 — REQ-015: added Entity: Asset (asset catalog with symbol UNIQUE, markets[], status); updated Portfolio.asset_id FK and symbol/market field notes.
- 2026-05-13 KST: bat-010 — REQ-009/023/028: added Entity: Daemon; added portfolios.managed_by_daemon_id; added auth_tokens.daemon_id; updated AuthToken State Rules (runtime_id vs daemon_id distinction, fail-closed policy); updated Portfolio Relationships; updated Model Summary.
- 2026-05-11 KST: bat-008 — REQ-011 AC-2: added portfolios.market column; added Entity: AuthToken (runtime_id field); added Entity: BrokerCredential; added Entity: LedgerTrade; updated Model Summary.
- 2026-05-11 KST: bat-006 — portfolios.portfolio_id changed to server-generated UUID PK; name column added with UNIQUE (owner_user_id, name) constraint; uq_portfolios_owner_name constraint documented; state rules updated.
- 2026-04-30 KST: Bootstrap baseline created from repository observation for initial StagePilot adoption.