74 lines
3.9 KiB
Markdown
74 lines
3.9 KiB
Markdown
# 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. |