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

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

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.

6.4 KiB Raw Blame History