docs/architecture/system-overview.md

Обзор системы

WealthLedger — локальное приложение для просмотра инвестиционных данных через безопасное server-side подключение к T-Bank Invest.

Поставленные возможности

• Аутентификация: access/refresh-сессии и защищённые маршруты.
• Подключение T-Bank: один зашифрованный token на User.
• Брокерские счета, Portfolio, Account Ledger и Future Cash Events.
• Frontend UI resilience: явные loading, error, empty и cached-snapshot состояния; initial и частичные loading-состояния показывают structural skeleton, а уже доступный контекст остаётся видимым при фоновом обновлении или действии пользователя.

Термины этих возможностей определяет глоссарий домена, а причины ключевых технических решений — ADR.

Локальные границы

• Frontend — React-клиент; он не вызывает T-Bank напрямую.
• Backend — NestJS API /api/v1, владеющий auth, SQLite-данными и T-Bank gRPC boundary.
• OpenAPI backend — единственный контракт frontend; committed client генерируется штатным workflow.
• Поставка остаётся локальной: deployment, Docker, CI/CD и облачные сервисы не входят в текущие границы.
• Portfolio Snapshot, summary списка Brokerage Account, Future Cash Events и Ledger pages существуют как read-only наблюдения текущего T-Bank connection; система не хранит историю портфеля, будущих событий или брокерских счетов как долговременные агрегаты. Summary списка сохраняет исходные валюты без FX- агрегации и может быть локально недоступна для отдельного счета.

Поток auth/session

sequenceDiagram
  participant U as User
  participant F as Frontend
  participant B as Backend
  participant D as SQLite
  U->>F: Регистрация или вход
  F->>B: POST /api/v1/auth/*
  B->>D: Создаёт User и Session
  B-->>F: Access token + refresh cookie
  F->>B: Защищённый запрос с Bearer token
  B-->>F: Данные или Problem Details
  F->>B: POST /api/v1/auth/refresh при истечении access token
  B->>D: Ротирует refresh token
  B-->>F: Новый access token + refresh cookie

Поток инвестиционных данных

sequenceDiagram
  participant U as User
  participant F as Frontend
  participant B as Backend
  participant D as SQLite
  participant T as T-Bank gRPC
  U->>F: Открывает счета или Portfolio
  F->>B: GET /api/v1/brokerage-accounts/* (Bearer)
  B->>D: Читает T-Bank connection
  B->>T: Запрос через server-side gRPC boundary
  T-->>B: Upstream-данные
  B-->>F: Нормализованные данные или Problem Details
  F-->>U: Экран с данными или локальным состоянием ошибки

Подробный статус локальных gates и deferred Prisma e2e находится в audit remediation registry.