Build 060.30: finalize Market Data Acquisition documentation

docs/architecture/project_structure.md

@@ -1,15 +1,108 @@
-# Project Structure
+# Структура проекта Dzentra
 
-## Корневые папки
-- `app/` — код приложения
-- `docs/` — документация
-- `infra/` — Docker и compose
+**Статус:** Current; Build 060.30.3
 
-## Внутри `app/src`
-- `bootstrap/`
-- `core/`
-- `telegram/`
-- `trading/`
-- `storage/`
-- `integrations/`
-- `shared/`
+Документ показывает назначение верхних уровней текущего checkout. Это
+навигационная карта, а не полный перечень файлов.
+
+## Корень репозитория
+
+```text
+dzentra_bot/
+├── app/                  Python-приложение, зависимости и тесты
+├── docs/                 архитектура, runbook, roadmap и история Builds
+├── infra/                Dockerfile и Docker Compose
+├── scripts/              общие quality-gate и вспомогательные scripts
+├── pyrightconfig.json    единая конфигурация статической проверки
+├── README.md             входная страница существующего checkout
+└── bootstrap_project.py  исторический генератор первоначального каркаса
+```
+
+`bootstrap_project.py` не является командой установки или запуска
+текущего проекта.
+
+## Каталог `app`
+
+| Путь | Назначение |
+|---|---|
+| `src/` | Production-код модульного монолита |
+| `tests/unit/` | Unit-тесты default offline regression |
+| `tests/static/` | Обязательный Pyright gate внутри default pytest |
+| `tests/integration/` | Opt-in локальные network/PostgreSQL сценарии |
+| `tests/stress/` | Fixed stress и opt-in soak проверки |
+| `tests/live/` | Только явно разрешённые проверки внешних endpoints |
+| `tests/support/` | Общие test harness и безопасные opt-in helpers |
+| `scripts/` | Ручные диагностические scripts |
+| `tools/` | Исследовательские Dzengi probes и сохранённые samples |
+| `.env.example` | Полный безопасный пример поддерживаемых настроек |
+| `requirements.txt` | Прямые Production dependencies |
+| `requirements.lock` | Полный hash-locked набор Production image |
+| `requirements-dev.txt` | Production dependencies плюс pytest и Pyright |
+
+Диагностические `app/scripts` и `app/tools` не запускаются автоматически
+вместе с Production Runtime.
+
+## Пакеты `app/src`
+
+```text
+src/
+├── bootstrap/       Composition Root и общий lifecycle
+├── core/            settings, logging и общие компоненты
+├── integrations/    внешние API вне Market Data vertical slice
+├── market_data/     acquisition, storage, access и replay
+├── notifications/   доставка и маршрутизация уведомлений
+├── runtime_events/  внутренняя Runtime Event система
+├── shared/          общие вспомогательные компоненты
+├── storage/         общий/исторический Storage foundation
+├── telegram/        Telegram UI и handlers
+├── trading/         торговая бизнес-логика и runtime-компоненты
+└── main.py          async entry point приложения
+```
+
+## Пакет `market_data`
+
+```text
+market_data/
+├── acquisition/  Canonical models, protocols, validation, Recovery и Runtime
+├── storage/      persistent repositories, checkpoint, partitions и Retention
+├── access/       Historical Access read-side
+└── replay/       Replay plan, deterministic clock и one-shot session
+```
+
+Фактические WebSocket Runtime, Consistency/Recovery и persistent writer
+consumer существуют только для Trades. REST-потоки Quotes/Candles
+продолжают использоваться Trading/UI; их persistence/read-side API
+реализованы отдельно.
+
+## Storage ownership
+
+`src/storage` и `src/market_data/storage` не являются взаимозаменяемыми:
+
+| Путь | Фактическая роль |
+|---|---|
+| `src/storage/session.py`, `schema.py`, `repositories/` | Базовая PostgreSQL-схема журнала и balance snapshots |
+| `src/storage/instrument_store.py`, `quote_store.py` | In-memory caches существующих consumers |
+| `src/storage/postgres_pool.py`, `migrations.py` | Общая инфраструктура pool/migrations, используемая Market Data Storage |
+| `src/market_data/storage/` | Канонические persistent Market Data contracts и repositories |
+| `src/market_data/access/` | Отдельный read-side сохранённых данных |
+| `src/market_data/replay/` | Отдельная deterministic Replay-вертикаль |
+
+Подробности приведены в [README пакета Storage](../../app/src/storage/README.md).
+
+## Документация
+
+| Каталог | Назначение |
+|---|---|
+| `docs/architecture/` | Current и target architecture |
+| `docs/operations/` | Актуальные эксплуатационные руководства |
+| `docs/migrations/` | Architecture/report документов отдельных Builds |
+| `docs/roadmap/` | План развития и исторические stage roadmaps |
+| `docs/stages/`, `docs/decisions/` | Исторические этапы и решения |
+| `docs/market_intelligence/` | Отдельная развиваемая Market Intelligence область |
+
+## Связанные документы
+
+- [Обзор архитектуры](overview.md)
+- [Текущая архитектура Trades Feed](trades_feed.md)
+- [Эксплуатация Trade Stream Runtime](../operations/trades_feed_runtime.md)
+- [Инструкция приложения](../../app/README.md)