docs: make project documentation self-contained

architecture/system-overview.md

@@ -1,7 +1,9 @@
 # Обзор системы
 
-WealthLedger — локальное приложение для просмотра инвестиционных данных через
-безопасное server-side подключение к T-Bank Invest.
+WealthLedger — локальное приложение для частного инвестора: оно связывает
+состав портфеля, операции, полученный доход и будущие выплаты по счетам T-Bank.
+Обзор объясняет систему сверху вниз. Детали сценариев и ответственность подсистем находятся
+в [карте возможностей](../features/README.md).
 
 ## Поставленные возможности
 
@@ -18,13 +20,84 @@ WealthLedger — локальное приложение для просмотр
   loading, error, empty и cached-snapshot состояния; initial и частичные
   loading-состояния показывают structural skeleton, а уже доступный контекст
   остаётся видимым при фоновом обновлении или действии пользователя.
+- [Все счета](../features/all-accounts.md): общий портфель, журнал, доходы
+  и будущие выплаты с сохранением принадлежности к счетам.
+- [Акции](../features/stock-detail.md) и [облигации](../features/bond-detail.md):
+  поиск, рыночные данные, личная позиция и события конкретного инструмента.
 
 Термины этих возможностей определяет [глоссарий домена](domain-glossary.md), а
 причины ключевых технических решений — [ADR](../adr/README.md).
 
+## Контекст системы
+
+```mermaid
+flowchart LR
+  U[Частный инвестор] -->|Смотрит инвестиции| W[WealthLedger]
+  W -->|Счета, позиции, операции и рынок| T[T-Bank Invest API]
+  W -->|Публичные данные облигаций| M[MOEX ISS]
+  W -->|Рейтинги выпусков| N[Реестр НКР]
+  W -->|Изображения логотипов| C[T-Bank Brands CDN]
+```
+
+T-Bank — источник личных брокерских данных и рынка. MOEX дополняет будущие
+события и показатели облигаций, НКР — рейтинг конкретного выпуска. Публичный
+рейтинг или календарь выпуска не подтверждает личное зачисление инвестору.
+Отсутствие записи и недоступность источника имеют разный смысл; детали —
+[Bond detail](../features/bond-detail.md).
+
+## Исполняемые части
+
+На уровне C4 containers здесь два приложения и локальная база. Каталоги
+`docs` и `specs` не являются runtime-компонентами.
+
+```mermaid
+flowchart LR
+  subgraph Browser[Браузер пользователя]
+    F[React SPA]
+  end
+  subgraph Local[Локальное окружение]
+    B[NestJS API]
+    D[(SQLite)]
+    B -->|Prisma: identity, sessions, connection| D
+  end
+  F -->|HTTP JSON, Bearer и auth cookie| B
+  B -->|gRPC over TLS, token пользователя| T[T-Bank Invest]
+  B -->|HTTPS, публичные данные| M[MOEX ISS]
+  B -->|HTTPS, публичный HTML| N[НКР]
+  F -->|HTTPS, изображения| C[Brands CDN]
+```
+
+- **Frontend** владеет представлением, навигацией и клиентским query cache.
+  Access token существует в памяти; refresh-cookie обслуживает browser.
+- **Backend** владеет identity, проверкой доступа, credentials брокера,
+  нормализацией, денежными расчётами и upstream-кэшем.
+- **SQLite** хранит локального User, sessions и зашифрованное подключение.
+- **Интеграции backend** обращаются к T-Bank, MOEX и НКР, сохраняя различия
+  личных данных брокера и публичных данных выпуска. Браузер получает
+  изображения логотипов непосредственно из публичного CDN.
+
+Frontend связывает пользовательские экраны навигацией. Backend объединяет
+аутентификацию, подключение брокера и инвестиционные сценарии через публичный API.
+Согласование адресов и origin — [локальный запуск](../development/local-workspace.md).
+
+## Хранимые данные
+
+Локальная база содержит идентичность пользователя и hash пароля, состояние
+его сессий со сроком действия, признаком отзыва и hash текущего refresh token,
+а также одно зашифрованное подключение T-Bank с временем подключения.
+Сессии и подключение принадлежат конкретному пользователю; plaintext пароля
+или broker token не является сохраняемым представлением credentials.
+
+Изменения связанных локальных данных требуют сохранения их целостности.
+Ротация сессии атомарно заменяет текущий refresh token: конкурентные запросы
+не могут оба выиграть. Сетевой вызов брокера и изменение локальной базы не
+образуют одну общую транзакцию. Финансовые наблюдения хранятся в ограниченном
+кэше, а не как долговременная история брокерских данных.
+
 ## Локальные границы
 
-- Frontend — React-клиент; он не вызывает T-Bank напрямую.
+- Финансовые API-запросы frontend проходят backend; browser не получает
+  T-Bank credential или gRPC client. Загрузка публичных логотипов — отдельный поток.
 - Backend — NestJS API `/api/v1`, владеющий auth, SQLite-данными и T-Bank
   gRPC boundary.
 - OpenAPI backend — единственный контракт frontend; committed client
@@ -37,24 +110,32 @@ WealthLedger — локальное приложение для просмотр
   долговременные агрегаты. Summary списка сохраняет исходные валюты без FX-
   агрегации и может быть локально недоступна для отдельного счета.
 
+## Предметная модель
+
+Локальный [User](domain-glossary.md#user) владеет
+[Session](domain-glossary.md#session) и одним
+[T-Bank connection](domain-glossary.md#t-bank-connection). Через подключение
+backend устанавливает доступ к [Brokerage Accounts](domain-glossary.md#brokerage-account).
+Идентификатор счёта из URL сам по себе не подтверждает этот доступ.
+
+[Portfolio](domain-glossary.md#portfolio) отвечает на вопрос «что есть сейчас»,
+[Account Ledger](domain-glossary.md#account-ledger) — «что исполнено»,
+[Realized Income](domain-glossary.md#realized-income-analytics) — «какие выплаты
+уже получены», будущие события — «что ожидается». Эти представления нельзя
+подменять друг другом. [Money](domain-glossary.md#money) сохраняет исходную
+валюту и точность; неизвестное значение отличается от нуля.
+
+Режим [«Все счета»](../features/all-accounts.md) агрегирует доступный состав,
+сохраняя происхождение строк; он не создаёт новый брокерский счёт. Обновление
+подключения меняет границу финансовых кэшей; перезапуск backend не восстанавливает
+прежние in-memory snapshots и cursor continuations из SQLite.
+
 ## Поток auth/session
 
-```mermaid
-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
-```
+Вход создаёт локальную сессию; последующие запросы используют access token.
+После перезагрузки SPA восстанавливает сессию через refresh-cookie. Схема,
+конкурентная ротация, logout и ограничения собраны у одного owner:
+[Authentication](../features/authentication.md).
 
 ## Поток инвестиционных данных
 
@@ -67,12 +148,22 @@ sequenceDiagram
   participant T as T-Bank gRPC
   U->>F: Открывает счета или Portfolio
   F->>B: GET /api/v1/brokerage-accounts/* (Bearer)
-  B->>D: Читает T-Bank connection
+  B->>D: Читает подключение текущего User
+  B->>T: Проверяет доступ к счёту
   B->>T: Запрос через server-side gRPC boundary
   T-->>B: Upstream-данные
   B-->>F: Нормализованные данные или Problem Details
   F-->>U: Экран с данными или локальным состоянием ошибки
 ```
 
-Подробный статус локальных gates и deferred Prisma e2e находится в
-[audit remediation registry](../development/audit-remediation.md).
+Схема показывает запрос, которому нужны upstream-данные. Повторные чтения могут
+обслуживаться кэшем по правилам конкретной feature. Проверку connection/account
+выполняет backend: запрос связывается с пользователем, его текущим подключением
+и доступными через него счетами, включая выдачу данных из кэша.
+Внешняя ошибка не становится нулевым балансом; допустимость stale snapshot и
+локальное восстановление описывает соответствующий сценарий.
+
+Причины server-side границы, шифрования и retry policy —
+[ADR 003](../adr/003-tbank-server-side-grpc-boundary.md),
+[ADR 004](../adr/004-encrypted-per-user-tbank-token.md) и
+[ADR 005](../adr/005-tbank-upstream-resilience.md).