docs: add baseline design

2026-08-12 21:13:05 +03:00
commit e610c83366
1 changed files with 92 additions and 0 deletions
@@ -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.