chore: initialize StagePilot baseline documentation and discovery/SRS/batches/releases structure

2026-04-30 13:19:48 +00:00
parent 7e9fbc1418
commit e362de205f
10 changed files with 723 additions and 0 deletions
@@ -0,0 +1,113 @@
+# Portfolio Hub Data Model
+
+- Baseline Mode: observed
+- Baseline Seed: .stagepilot/bootstrap/baseline.yaml
+- Status: confirmed
+- Owner: repository-maintainers
+- Last Updated (KST): 2026-04-30 22:13
+- Source Discovery / Batch: bootstrap-baseline
+
+## 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
+
+## 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 :: text :: stable portfolio primary key
+- symbol :: text :: traded asset symbol for the portfolio
+- 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
+
+### 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
+
+### State Rules
+
+- Portfolio names are required and are backfilled from symbol when older rows are migrated.
+- 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.
+
+## 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.
+
+## 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-04-30 KST: Bootstrap baseline created from repository observation for initial StagePilot adoption.