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-11 00:00
• Source Discovery / Batch: bootstrap-baseline, bat-001, bat-006, bat-008

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
• AuthToken :: issued client or service token with permission and optional runtime_id
• BrokerCredential :: encrypted broker API credentials per user-broker pair
• LedgerTrade :: idempotent trade execution record keyed by (asset_id, order_id, execution_id)

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}
• symbol :: text :: traded asset symbol for the portfolio
• market :: text|null :: market identifier for the asset (e.g., exchange code); added by migration 20260502_0014
• 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

Uniqueness Constraints

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

Relationships

• User :: owner_user_id links a portfolio to its owning user when ownership is assigned
• 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 :: opaque runtime identifier assigned at service-token issuance; unique (partial index on non-NULL values); added by migration 20260502_0014
• 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 with runtime_id are the only tokens accepted by v1 API endpoints; GET /v1/user_info returns HTTP 404 if runtime_id is None.
• Token permission gates both HTTP API guards and CLI mutation capabilities.

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-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.