pocketledger-architecturelisted

# PocketLedger architecture Read this before the first edit to `app/`. Inferring the conventions from one file usually reproduces that file's accidents rather than the pattern. ## The layers ``` HTTP request │ ▼ app/api/routers/ HTTP shape, status codes, validation, auth dependency │ → returns Pydantic schemas, never ORM models ▼ app/services/ business logic, invariants, ownership scoping │ → returns ORM models, raises domain errors ▼ app/models/ SQLAlchemy 2.0 typed mappings, constraints │ ▼ PostgreSQL ``` Two rules make the layering real rather than decorative: **A router contains no business logic.** It unpacks the request, calls one service function, and converts the result to a schema. If a router branches on domain state, that branch belongs in the service. **A service imports nothing from FastAPI.** Services take a `Session` and a `User` and raise domain errors from `app.core.errors`. The moment a service knows about HTTP, it can no longer be tested or reused without HTTP. Supporting modules: | Path | Holds | |---|---| | `app/schemas/` | Pydantic request and response models | | `app/core/config.py` | settings, and the production readiness guard | | `app/core/errors.py` | domain errors, mapped to HTTP by `api/error_handlers.py` | | `app/core/security.py` | password hashing, JWT encode and decode | | `app/api/deps.py` | `get_current_user` and other request dependencies | | `app/