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,74 @@
+# Portfolio Hub Runtime Flows
+
+- 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
+- Primary Runtime: mixed
+
+## Project Summary
+- PortfolioHub exposes portfolio management and trading ledger workflows through a FastAPI service and a companion CLI.
+
+## Purpose
+- This document is the current approved execution-flow baseline for the project.
+- It is a cross-cutting reference document for Discovery, REQ, Batch Design, Batch Verification, and implementation updates.
+
+## Scope
+- Covers representative command and runtime flows.
+- Does not duplicate full acceptance criteria or low-level implementation details.
+
+## Covered Entry Points
+
+- uvicorn app.main:app :: serve the authenticated HTTP API, OpenAPI docs, and startup bootstrap hooks
+- pfhub :: run operational CLI commands for health, users, portfolios, strategies, and service tokens
+- alembic upgrade head :: apply ordered database schema migrations for persistent environments
+
+## Shared Components
+
+- app/core/config.py Settings loading and environment normalization
+- app/core/auth.py permission guards and auth context resolution
+- app/services/* business logic for auth, users, portfolios, and strategy sets
+- app/repositories/factory.py repository selection and Postgres config construction
+- app/repositories/postgres.py Postgres persistence, schema bootstrap, and query execution
+
+## Flow: `HTTP API Request Handling`
+
+1. Uvicorn loads app.main:app, which creates the FastAPI application from create_app().
+2. create_app() loads Settings, registers middleware and routers, and wires exception handlers.
+3. During lifespan startup, the app optionally bootstraps an initial admin user when DB mode and bootstrap credentials are configured.
+4. Incoming requests pass through auth and permission dependencies before services mutate state or query persistence.
+5. Services call the repository factory, which returns PostgresPortfolioRepository only when PORTFOLIOHUB_DB_ENABLED=true.
+6. Routes serialize domain results into app/schemas response models or return HTTP 204 for deletion flows.
+
+## Flow: `CLI Operational Command Execution`
+
+1. The pfhub entrypoint builds a Typer application and injects Settings, console output, and a repository factory into AppContext.
+2. Command groups parse arguments, confirmations, and output format selection before invoking the relevant service or repository methods.
+3. Database setup commands use the shared settings layer to target the configured PostgreSQL or TimescaleDB instance.
+4. Read commands print table or JSON output, while write commands require explicit confirmation unless --force is supplied.
+5. Command failures surface as validation errors, feature-not-ready errors, or persistence and auth exceptions.
+
+## Flow Constraints
+
+- Persistence-dependent HTTP and CLI flows require PORTFOLIOHUB_DB_ENABLED=true plus valid TimescaleDB connection settings.
+- Permission levels read, trade-write, and admin must map consistently across API guards, issued tokens, and CLI mutations.
+- Request validation and auth resolution should happen before persistence mutation or response rendering.
+- The health endpoint remains unauthenticated so infrastructure can probe readiness without a token.
+
+## Current Gaps / Planned Changes
+
+- End-to-end validation against a real PostgreSQL or TimescaleDB deployment is still pending.
+- Redis and Loki are configured as supporting infrastructure but are not yet represented as explicit runtime flows.
+- Ownership-scoped authorization remains an open evolution area after bootstrap.
+
+## Update Triggers
+
+- Update this document when a command entry point changes.
+- Update this document when a runtime orchestration path changes.
+- Update this document when a batch changes the approved flow baseline.
+
+## Change Log
+
+- 2026-04-30 KST: Bootstrap baseline created from repository observation for initial StagePilot adoption.