From 34577dc7956f90f73c50ba067ff8ecc7e751853c Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Wed, 12 Aug 2026 21:14:22 +0300 Subject: [PATCH] docs: remove misplaced baseline design --- .../specs/2026-08-12-baseline-design.md | 92 ------------------- 1 file changed, 92 deletions(-) delete mode 100644 superpowers/specs/2026-08-12-baseline-design.md diff --git a/superpowers/specs/2026-08-12-baseline-design.md b/superpowers/specs/2026-08-12-baseline-design.md deleted file mode 100644 index 9f37183..0000000 --- a/superpowers/specs/2026-08-12-baseline-design.md +++ /dev/null @@ -1,92 +0,0 @@ -# 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.