portfolio-hub/docs/project-structure.md

# Portfolio Hub Project Structure

- Baseline Mode: observed
- Baseline Seed: .stagepilot/bootstrap/baseline.yaml
- Status: confirmed
- Owner: repository-maintainers
- Last Updated (KST): 2026-05-01 00:00
- Source Discovery / Batch: bootstrap-baseline, bat-001

## 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, service tokens, and broker credentials
- 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.
  - v1 route surfaces: `v1_assets.py` (GET /v1/assets), `v1_user_info.py` (GET /v1/user_info), `v1_ledger.py` (POST /v1/assets/{asset_id}/ledger/trades).
  - All v1 endpoints require service-token authentication (token_source=db, token_type=service).
- app/cli/
  - Defines the Typer entrypoint, command groups, output helpers, and operator-facing command flows.
  - Command groups: `portfolio`, `strategy`, `user`, `service-token`, `credential` (broker credential management), and health commands (`health-check`, `init-db`, `migrate-db`).
- app/core/
  - Owns configuration loading, auth guards, security helpers, and shared error handling.
  - `encryption.py`: Fernet-based credential payload encrypt/decrypt helpers. Reads `CREDENTIAL_ENCRYPTION_KEY` env var via `Settings.require_credential_encryption_key()`.
- 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.
  - `v1.py`: Contract schemas for v1 API (AssetItem, UserInfoResponse, BrokerItem, LedgerTradeRequest/Response).
- 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

- 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.
- Broker credential write path (upsert) is available only via CLI; no public HTTP API exists for credential registration yet.

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