# Dzentra

Dzentra — модульный монолит автоматической торговой системы с
Telegram-интерфейсом. В текущем принятом Production scope полностью
собрана вертикаль Trades Feed: получение сделок, проверка
последовательности, reconnect/recovery, опциональное сохранение в
PostgreSQL и восстановление после перезапуска.

## Текущий scope

- Production ingestion, Consistency, Recovery, persistent checkpoint и
  Startup Recovery реализованы для Trades.
- Historical Access и deterministic Replay доступны как отдельные API и
  не запускаются автоматически.
- REST-потоки Quotes и Candles продолжают использоваться Trading/UI.
  Новые WebSocket Runtime, Consistency/Recovery и persistent writer
  wiring для них пока не подключены.
- Retention и создание месячных партиций выполняются только явным вызовом.
- Обычный запуск приложения требует PostgreSQL для журнала и balance
  snapshots, даже если Trade Stream и Market Data Storage выключены.

Подробное фактическое состояние описано в
[архитектуре Trades Feed](docs/architecture/trades_feed.md).

## Быстрый старт существующего checkout

Требуются Python 3.12, доступный PostgreSQL и Telegram Bot Token. Команды
выполняются из корня репозитория:

```bash
python3.12 -m venv app/.venv
app/.venv/bin/python -m pip install \
  --require-hashes \
  -r app/requirements-dev.lock
app/.venv/bin/python -m pip check
test -e app/.env || cp app/.env.example app/.env
```

Заполните созданный `app/.env`, не добавляйте его в Git и не
перезаписывайте уже существующий файл. Затем запустите приложение:

```bash
cd app
.venv/bin/python -m src.main
```

Настройки режимов, PostgreSQL и безопасный Docker-запуск приведены в
[эксплуатационном руководстве](docs/operations/trades_feed_runtime.md).
Более подробная инструкция для разработчика находится в
[app/README.md](app/README.md).

## Обязательные проверки

Из корня репозитория:

```bash
./scripts/check_python_types.sh
app/.venv/bin/python scripts/check_documentation_integrity.py
```

Ожидаемый результат Pyright — `0 errors, 0 warnings`, а documentation
gate — `issues=0`. Обычная offline-регрессия запускается из `app`:

```bash
cd app
.venv/bin/python -m pytest -q
```

Default pytest-набор исключает opt-in группы `integration`, `stress` и
`live`, но включает статическую проверку Pyright. Целевой тест не
заменяет полный type gate.

Локальный эквивалент первого CI gate запускает quality, offline regression
и безопасную loopback integration-проверку:

```bash
./scripts/run_ci_gate.sh all
```

Workflow пока запускается только вручную. Его границы, runner contract и
критерии зелёного canary описаны в [CI runbook](docs/operations/ci_gate.md).

## Навигация

- [Обзор архитектуры](docs/architecture/overview.md)
- [Структура проекта](docs/architecture/project_structure.md)
- [Текущая архитектура Trades Feed](docs/architecture/trades_feed.md)
- [Эксплуатация Trade Stream Runtime](docs/operations/trades_feed_runtime.md)
- [CI gate и первый canary](docs/operations/ci_gate.md)
- [Архитектура Build 060.30](docs/migrations/build_060_30_architecture.md)

## Исторический bootstrap

`bootstrap_project.py` — исторический генератор первоначального каркаса.
Для установки или запуска существующего checkout его использовать не
нужно.