commit e610c83366045e5e8dab71ea5edbe7796bb78364 Author: Sergey Krylov Date: Wed Aug 12 21:13:05 2026 +0300 docs: add baseline design diff --git a/superpowers/specs/2026-08-12-baseline-design.md b/superpowers/specs/2026-08-12-baseline-design.md new file mode 100644 index 0000000..9f37183 --- /dev/null +++ b/superpowers/specs/2026-08-12-baseline-design.md @@ -0,0 +1,92 @@ +# WealthLedger Baseline Design + +## Purpose + +Establish the minimum documented and technical foundation for a local, multi-user investment portfolio viewer. This baseline contains no completed business feature; it makes the later authentication, T-Bank connection, accounts, and portfolio changes consistent and independently deliverable through OpenSpec. + +## Scope + +- Keep `frontend`, `backend`, `specs`, and `docs` as independent Git repositories. The workspace root and `references` remain outside Git. +- Add an overview `AGENTS.md` at the workspace root and repository-specific `AGENTS.md` files. +- Add a local `MVP.md` at the workspace root as the compact delivery map and record of decisions from the grilling session. +- Create the documentation structure: `adr/`, `architecture/`, `development/`, and `features/`. +- Record architecture decisions for Prisma with SQLite, Nest-generated OpenAPI, the T-Bank gRPC boundary, encrypted T-Bank tokens, upstream resilience, auth sessions, and React Query caching. +- Adapt only the frontend template infrastructure: FSD structure, Russian i18n, Mantine, the light finance theme, responsive application shell, routing, typed OpenAPI-client generation, and quality tooling. Exclude all Todo domain code, mock scenarios, and demo pages. +- Prepare the Nest foundation: `/api/v1` prefix, Swagger/OpenAPI output, environment validation, CORS restricted to configured frontend origins, common safe errors, and Prisma/SQLite integration. +- Establish the OpenSpec `baseline` change. It describes infrastructure only; it must not introduce working authentication, a T-Bank connection, account retrieval, or portfolio rendering. + +## Deferred Work + +- `add-authentication`: registration, login, refresh/logout, profile endpoint, and protected routes. +- `add-tbank-connection`: token CRUD, validation with T-Bank `GetAccounts`, encryption, and upstream controls. +- `add-brokerage-accounts`: active-account list and its states. +- `add-portfolio-view`: account portfolio, positions, cash balances, instrument metadata fallback, and freshness display. +- Docker, CI/CD, deployment, password recovery/change, account deletion, dark mode, portfolio history, transaction history, manual refresh, server-side pagination, and currency conversion. + +## Target Architecture + +```mermaid +flowchart LR + UI[React/Vite frontend] -->|REST /api/v1| API[NestJS backend] + API -->|Prisma| DB[(SQLite)] + API -->|gRPC only| TB[T-Bank Invest API] + API -->|OpenAPI JSON| GEN[Generated frontend client] +``` + +The frontend never calls T-Bank and never receives a T-Bank token. Backend controllers expose stable REST DTOs and isolate all upstream protobuf details in a dedicated `TBankModule`. Future frontend types and request modules are generated from the Nest Swagger document and committed to the frontend repository. + +## Security And Session Model + +- Users register with a lowercased, unique email and a password of at least 12 characters. +- Passwords and persisted refresh tokens use bcrypt with 12 salt rounds. +- Access JWTs live for 15 minutes and only in frontend memory. +- Rotating refresh JWTs live for 7 days in an `httpOnly`, `SameSite=Lax` cookie. The cookie `secure` flag depends on the environment. +- A T-Bank token is one per user. It is validated with `GetAccounts`, encrypted before SQLite persistence with required `TOKEN_ENCRYPTION_KEY`, and is never returned to the browser. +- Logs must not contain passwords, T-Bank tokens, JWTs, authorization headers, or cookies. + +## T-Bank Data And Resilience + +- The application accepts user-provided tokens as read-only by convention and itself makes only read operations. +- Only active investment accounts are shown. +- Backend responses use normalized DTOs rather than protobuf fields. Decimal financial values are strings plus currency; frontend must not perform floating-point arithmetic. +- A global outbound queue starts with a configurable limit of five T-Bank requests per second. +- Only temporary upstream failures and `429` receive bounded exponential-backoff retries. Authentication errors do not retry. +- Backend has a 30-second in-memory cache for account and portfolio data, and an in-memory instrument metadata cache for at least one day. Cached responses retain the actual upstream-success timestamp. +- Missing instrument metadata falls back to `figi`; it cannot suppress otherwise available portfolio amounts. +- A `401` or `403` from T-Bank marks the connection as requiring a new token rather than deleting it. + +## MVP User Experience + +- Routes: `/login`, `/register`, `/accounts`, `/accounts/:accountId`, `/settings`. +- Successful authentication opens `/accounts`. +- `/accounts` shows an action to connect T-Bank when no token exists. +- The accounts and portfolio screens fetch when opened only: no focus refetch and no manual refresh action. React Query remains the browser cache layer. +- An empty portfolio is a normal state, not an error. +- One account failing to load must not hide other retrieved accounts. +- Position rows default to current value descending, without a sort control. +- The MVP uses a light-only Mantine theme based on the `fin-tracker` color tokens. The app shell has desktop sidebar navigation and a mobile bottom navigation, restricted to Accounts and Settings. + +## Documentation And SDD Rules + +```mermaid +flowchart LR + Proposal[OpenSpec change] --> Implementation[Code and critical tests] + Implementation --> Verify[opsx-verify] + Verify --> Docs[Feature docs and Mermaid diagrams] + Docs --> Archive[Archive change] +``` + +- `docs/adr/` contains durable technical decisions. +- `docs/features/` explains completed user-facing behavior, API flow, constraints, and Mermaid diagrams. +- `docs/architecture/` contains system structure and cross-feature behavior. +- `docs/development/` contains workflow and contributor guidance. +- Each functional OpenSpec change closes only after all its artifacts, implementation, critical tests, `opsx-verify`, and associated documentation are complete. + +## Baseline Acceptance Criteria + +- The four repositories have clear local AI guidance and the root has a workspace map. +- `MVP.md` accurately records the decisions above without acting as a second detailed specification. +- Docs repository has the agreed documentation structure and the required ADRs. +- Frontend has no Todo domain behavior and contains the agreed technical and visual foundation. +- Backend exposes versioned Swagger/OpenAPI and has local SQLite/Prisma and environment/CORS foundations. +- The OpenSpec baseline change is created and fully specified before implementation begins.