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,134 @@
+# Portfolio Hub Project Structure
+
+- 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.
+
+## Tech Stack
+- Python 3.12
+- FastAPI
+- Typer
+- Pydantic Settings
+- Psycopg
+- Alembic
+- PostgreSQL/TimescaleDB
+- Docker Compose
+
+## Primary Runtime
+- Type: mixed
+- Planned 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
+
+## Purpose
+- This document is the current approved repository and package structure baseline.
+- It is a cross-cutting reference document for Discovery, REQ, Batch Design, Batch Verification, and implementation updates.
+
+## Scope
+- Covers the top-level repository layout and package or module boundaries.
+- Does not duplicate detailed business rules, acceptance criteria, or implementation-only function signatures.
+
+## Top-Level Structure
+
+```text
+.
+|-- .github/
+|   |-- instructions/
+|   |-- prompts/
+|   |-- runbooks/
+|   |-- scripts/
+|   |-- skills/
+|   `-- templates/
+|-- .stagepilot/
+|   `-- bootstrap/
+|-- .vendor/
+|   `-- stage-pilot/
+|-- app/
+|   |-- api/
+|   |-- cli/
+|   |-- core/
+|   |-- db/
+|   |-- domain/
+|   |-- repositories/
+|   |-- schemas/
+|   `-- services/
+|-- docs/
+|   |-- batches/
+|   |-- discovery/
+|   |-- releases/
+|   `-- srs/
+|-- migrations/
+|   `-- versions/
+|-- tests/
+|-- temp/
+|-- README.md
+|-- alembic.ini
+|-- docker-compose.local-test.yml
+`-- pyproject.toml
+```
+
+## Package / Module Responsibilities
+
+- .github/
+  - Hosts StagePilot skills, document templates, and helper scripts such as stagepilot-doctor and stagepilot-bootstrap-seed.
+- app/api/
+  - Defines FastAPI route surfaces for health, authentication, users, strategy sets, and portfolios.
+- app/cli/
+  - Defines the Typer entrypoint, command groups, output helpers, and operator-facing command flows.
+- app/core/
+  - Owns configuration loading, auth guards, security helpers, and shared error handling.
+- app/domain/
+  - Holds framework-light domain models shared by services, routes, and repositories.
+- app/repositories/
+  - Provides the repository protocol, repository factory, and concrete Postgres persistence implementation.
+- app/schemas/
+  - Defines request and response schemas for HTTP contracts.
+- app/services/
+  - Implements business logic for auth, portfolios, strategy sets, and users.
+- migrations/
+  - Stores Alembic environment files and ordered schema revisions for persistent database changes.
+- tests/
+  - Covers API behavior, auth flows, CLI behavior, domain services, portfolio comments, tags, ownership, and users.
+- docs/
+  - Stores active SDLC indices and cross-cutting baseline documents.
+
+## Dependency Rules
+
+- Interface layers in app/api/ and app/cli/ should reach persistence through app/services/ and app/repositories/factory.py rather than importing database code directly.
+- app/domain/models.py remains the shared contract between services, repositories, and interface adapters.
+- app/repositories/postgres.py owns SQL details; migrations/versions/ owns ordered schema evolution history.
+- app/core/config.py is the shared configuration source for both the FastAPI app and the Typer CLI.
+- tests/ should prefer public API, CLI, or service entrypoints over asserting against private persistence details unless a regression requires it.
+
+## Shared Boundaries
+
+- PortfolioRepository is the abstraction boundary between business logic and concrete persistence.
+- Settings and auth primitives are shared across API requests, CLI commands, and startup bootstrap behavior.
+- docs/ holds SDLC source-of-truth artifacts, while temp/ remains scratch or legacy material outside the active document flow.
+- .vendor/stage-pilot/ is a vendored upstream toolkit and should not be treated as the active host source of truth.
+
+## Current Gaps / Planned Changes
+
+- No active Discovery, REQ, Batch, or Release units exist yet; this baseline only bootstraps the document structure.
+- The non-DB repository path intentionally raises a feature-not-ready error when persistence is disabled.
+- Redis and Loki settings exist, but their runtime ownership and module boundaries are not yet represented in active docs.
+
+## Update Triggers
+
+- Update this document when package boundaries change.
+- Update this document when new top-level runtime or domain modules are added.
+- Update this document when a batch changes the approved structure baseline.
+
+## Change Log
+
+- 2026-04-30 KST: Bootstrap baseline created from repository observation for initial StagePilot adoption.