# Структура проекта Dzentra

**Статус:** Current; Build 060.30.3

Документ показывает назначение верхних уровней текущего 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)