# 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.