dzentra_bot/docs/architecture/dzentra_target_architecture.md

Dzentra Target Architecture

Контроль документа

Свойство	Значение
Тип	Target Architecture
Статус	Active Baseline
Версия	1.0
Дата	2026-07-31
Проект	Dzentra

---

1. Назначение

Документ фиксирует целевую архитектурную карту Dzentra и связывает:

• фактическую структуру существующего проекта;
• выполняемую Build-by-Build миграцию;
• будущие подсистемы профессиональной автоматической торговой системы;
• обязательное направление зависимостей между доменами.

Документ не требует немедленного создания всех перечисленных каталогов и не заменяет архитектурные спецификации отдельных Build.

Целевая архитектура отвечает на вопрос:

Какие ответственности должны существовать в системе и как они могут взаимодействовать?

Последовательность реализации и текущий статус определяет docs/roadmap/master-roadmap.md.

---

2. Текущий контекст

Dzentra является работающим modular monolith, который постепенно мигрирует из Telegram trading bot в модульную алгоритмическую торговую платформу.

Проект не является greenfield-системой. В нём одновременно существуют:

• принятые новые архитектурные слои;
• рабочие legacy-компоненты;
• временные compatibility boundaries;
• будущие целевые подсистемы.

Поэтому целевой каталог нельзя создавать механическим переносом файлов. Любое изменение ownership или направления зависимостей выполняется отдельным Build после анализа фактических consumers.

---

3. Верхнеуровневая карта

External Exchanges and Data Sources
                │
                ▼
┌───────────────────────────────────────────────┐
│ Market Data                                  │
│ Acquisition → Canonicalization → Quality     │
│                    │                          │
│                    ├── Live / Operational     │
│                    └── Storage → Replay       │
└───────────────────────────────────────────────┘
                │ Canonical Live or Replay Data
                ▼
┌───────────────────────────────────────────────┐
│ Market Intelligence                          │
│ Processing → Features → Market State         │
│ → Scenario Evaluation                        │
└───────────────────────────────────────────────┘
                │ Analysis Results
                ▼
┌───────────────────────────────────────────────┐
│ Trading                                      │
│ Strategy / Decision → Portfolio / Risk       │
│ → Order Management → Execution               │
│ → Position and Account Reconciliation        │
└───────────────────────────────────────────────┘
                │ Commands and Reports
                ▼
             Exchange

Все уровни обслуживаются общей Platform-плоскостью:

Runtime and Scheduling
Event Contracts
Configuration and Secrets
Logging, Audit and Observability
Resilience and Recovery
Security
Deployment and Operations

Logging, Audit, Monitoring и Runtime не являются последними этапами торгового конвейера. Они действуют на всех уровнях системы.

---

4. Market Data

4.1. Market Data Acquisition

Назначение: получение внешних рыночных и справочных данных.

Целевые семейства Feed:

• Instrument Reference Data;
• Quotes;
• OHLCV / Candles;
• Trades / Time & Sales;
• Order Book;
• Derivatives Market Data;
• Market Index;
• Exchange Time;
• Exchange and Instrument Status.

Каждый Feed развивается как самостоятельный vertical slice:

external document
    ↓
schema validation
    ↓
parser / transport model
    ↓
value validation
    ↓
mapper
    ↓
canonical model
    ↓
handler / feed / service

REST и WebSocket могут иметь независимые transport pipelines, но до передачи downstream обязаны сходиться в одну source-independent Canonical Model.

Текущее размещение:

app/src/market_data/acquisition/

Текущий активный результат: Production Runtime для Trades Feed завершён в Build 060.25.

4.2. Validation, Canonicalization and Data Quality

Назначение:

• проверять структуру внешних документов;
• проверять допустимость значений;
• нормализовать время, числовые значения и идентификаторы;
• преобразовывать transport data в Canonical Models;
• контролировать дубликаты, порядок и пропуски;
• формировать явные признаки качества и freshness.

Эта ответственность сейчас распределена между:

adapters/
validation/
models/
consistency/
recovery/

Build 061.00 должен сначала проверить фактические границы, а уже затем решить, требуется ли отдельный каталог normalization.

Schema Validation, Value Validation, Mapping, Stream Consistency и Missing Data Recovery не должны смешиваться в один универсальный компонент.

4.3. Operational Market State

Оперативное состояние необходимо для работы активного потока:

• последний принятый Trade;
• deduplication window;
• состояние подписок;
• connection generation;
• liveness и reconnect state.

Оно не является долговременной историей рынка.

TradeStreamState принадлежит Consistency Layer, а не общему Market Data Storage и не WebSocket Transport.

4.4. Persistent Market Data Storage

Назначение: долговременно хранить Canonical Market Data для:

• восстановления после перезапуска;
• исторических запросов;
• Replay;
• разработки и проверки аналитики;
• backtesting;
• аудита качества данных.

Хранилище должно определить:

• raw и canonical retention policy;
• ключи идемпотентности;
• порядок и уникальность событий;
• партиционирование по типу данных, символу и времени;
• правила исправления и повторной загрузки;
• provenance и версию Canonical schema.

Существующий app/src/storage/ нельзя автоматически считать готовым Market Data Storage. Его фактические контракты проверяются в Build 060.27.

4.5. Historical Access and Replay

Назначение:

• исторические запросы;
• последовательное воспроизведение Canonical Market Data;
• управляемые виртуальные часы;
• одинаковые контракты данных для production и replay consumers;
• основа backtesting и воспроизводимой диагностики.

Replay должен воспроизводить порядок событий и не обходить Canonical Models или validation guarantees.

---

5. Market Intelligence

5.1. Market Data Processing

Формирует устойчивое состояние и базовые рыночные представления:

• Candle aggregation;
• Order Book reconstruction;
• best bid / ask / mid / spread;
• trade-flow aggregation;
• временные окна;
• подтверждённые market events.

Processing не принимает торговых решений.

5.2. Feature Engineering

Формирует производные признаки:

• returns и momentum;
• volatility;
• relative и abnormal volume;
• trade-flow intensity и delta;
• Order Book imbalance и microprice;
• liquidity;
• time/session features;
• statistical и cross-market features;
• derivatives features.

Canonical Trade price, quantity и timestamp уже являются исходными данными и не требуют отдельного дублирующего Trade Facts model без подтверждённого consumer.

5.3. Market State Estimation

Интерпретирует признаки и определяет:

• market structure;
• trend и range;
• momentum и correction;
• volatility regime;
• liquidity regime;
• order-flow state;
• market phase;
• microstructure context.

Текущее основное размещение:

app/src/trading/market_intelligence/

Изменение этого ownership требует отдельного архитектурного Build.

5.4. Scenario Evaluation

Dzentra рассматривает прогнозирование как оценку нескольких возможных сценариев:

• scenario generation;
• probability estimation;
• ranking;
• confidence and uncertainty.

Scenario Evaluation является опциональной аналитической возможностью. Strategy, которой отдельный прогноз не требуется, не должна создавать фиктивную зависимость от Forecasting.

---

6. Trading

6.1. Strategy and Trading Decision

Преобразует рыночный анализ в торговое намерение:

• enter;
• hold;
• reduce;
• exit;
• do nothing.

Результат Decision не является биржевым ордером и не должен напрямую вызывать Transport.

6.2. Portfolio and Risk

Проверяет и ограничивает торговое намерение:

• допустимый размер позиции;
• leverage и margin;
• общий капитал под риском;
• концентрацию по символам;
• drawdown и loss limits;
• pre-trade, continuous и emergency risk controls.

Risk не является только одним последовательным шагом после Strategy. Он может запрещать вход, изменять размер позиции и останавливать уже активное исполнение.

6.3. Order Management System

Отвечает за внутренний жизненный цикл собственных заявок:

• создание client order identity;
• переходы состояния заявки;
• amend / cancel;
• partial fills;
• deduplication;
• reconciliation с биржей;
• восстановление после reconnect и restart.

OMS не следует смешивать с Market Trades Feed: рыночная сделка и исполнение собственной заявки являются разными предметными сущностями.

6.4. Execution Management

Отвечает за:

• преобразование одобренного намерения в execution command;
• выбор цены и способа исполнения;
• маршрутизацию на биржу;
• контроль slippage, liquidity и freshness;
• обработку transport и exchange errors.

Текущее основное размещение:

app/src/trading/execution/

6.5. Position and Account Reconciliation

Сопоставляет локальное состояние с биржей:

• позиции;
• balances;
• fills;
• open orders;
• fees;
• realized и unrealized PnL.

Биржевое состояние является внешним фактом и должно периодически сверяться, а не только вычисляться из локальных событий.

---

7. Platform and Governance

Runtime and Scheduling

• явные владельцы задач и ресурсов;
• конечные timeouts;
• детерминированные startup и shutdown;
• controlled retry/reconnect;
• отсутствие скрытого fire-and-forget.

Event Contracts

• типизированные и версионируемые события;
• явная граница между market, runtime, execution и audit events;
• контролируемое ordering;
• отсутствие чувствительных transport payload в логах.

Configuration and Secrets

• feature flags безопасны по умолчанию;
• URL, symbols и credentials задаются явно;
• production secrets не попадают в код, документацию и события.

Logging, Audit and Observability

• технические логи;
• domain audit trail;
• Trade Journal;
• metrics, latency и data freshness;
• health и liveness;
• alerting;
• объяснение причин торгового решения.

Resilience

• idempotency;
• reconnect;
• Recovery;
• persistent checkpoint;
• startup reconciliation;
• controlled degradation;
• failure isolation.

Backtesting and Simulation

Backtesting является отдельной capability, но переиспользует:

• Canonical Market Data;
• Replay;
• deterministic clock;
• production Feature, Decision и Risk contracts;
• exchange/OMS simulator.

Отдельная копия торговой логики только для backtest не допускается.

---

8. Правила зависимостей

Разрешённое основное направление:

Market Data
    ↓
Market Intelligence
    ↓
Trading Decision
    ↓
Portfolio / Risk
    ↓
OMS / Execution
    ↓
Exchange Integration

Обязательные ограничения:

• Market Data не импортирует Trading;
• Canonical Models не зависят от Dzengi transport schema;
• Market Intelligence не управляет WebSocket lifecycle;
• Strategy не отправляет биржевую заявку напрямую;
• Execution не изменяет правила Market Data Consistency;
• Telegram UI не является владельцем domain state;
• Storage не вызывает торговые решения;
• Backtesting использует те же domain contracts, что production;
• Platform-компоненты не получают лишнюю предметную ответственность.

Обратная информация от Exchange возвращается через явные execution, order, account и runtime events, а не через обратные импорты между слоями.

---

9. Политика каталогов

Логический домен и физический каталог не обязаны иметь одинаковое имя.

Текущее соответствие:

Ответственность	Фактическое размещение
Market Data Acquisition	app/src/market_data/acquisition/
Application Runtime Composition	app/src/bootstrap/
Runtime Events	app/src/runtime_events/ и локальные runtime events
Storage foundation	app/src/storage/
Market Intelligence	app/src/trading/market_intelligence/
Trading Decision	app/src/trading/decision/
Execution	app/src/trading/execution/
Position	app/src/trading/position/
Trade Journal	app/src/trading/journal/
Exchange Integration	app/src/integrations/exchange/

Новый каталог создаётся только когда:

1. ответственность подтверждена фактическими consumers;
2. определён публичный контракт;
3. существующее ownership признано неверным;
4. подготовлен отдельный migration plan;
5. проверено направление импортов.

Предложенные имена вроде analytics/features, market_data/normalization или market_data/storage являются логическими ориентирами, а не заранее утверждённой файловой структурой.

---

10. Current-to-target status

Область	Состояние
Market Data Acquisition foundation	Реализуется Build-by-Build
Trades Feed production runtime	Completed — Build 060.25
Runtime integration/stress verification	Next — Build 060.26
Persistent Market Data Storage	Planned — Build 060.27
Persistent Checkpoint / Startup Recovery	Planned — Build 060.28
Historical Access / Replay	Planned — Build 060.29
Validation ownership audit/refactoring	Planned — Build 061.00
Market Intelligence	Существующая активная подсистема
Decision / Execution / Position	Существующие подсистемы, требуют будущих boundary audits
OMS / Reconciliation	Целевая ответственность, отдельный план не утверждён
Backtesting	Целевая capability после Storage и Replay
Operations / Deployment	Целевая cross-cutting программа

Completed означает завершение утверждённого Build, а не окончательную сертификацию всей подсистемы для любой production-нагрузки.

---

11. Управление изменениями

Этот документ изменяется только когда меняется:

• ownership домена;
• публичная архитектурная граница;
• разрешённое направление зависимостей;
• целевая карта подсистем.

Статус конкретного Build изменяется в master-roadmap.md и его migration report.

Детали реализации, тестовые evidence и локальные решения фиксируются в:

docs/migrations/build_<number>_architecture.md
docs/migrations/build_<number>.md
docs/decisions/

При конфликте:

1. фактический код и тесты определяют текущее поведение;
2. принятый Build architecture document определяет локальное решение;
3. настоящий документ определяет целевую границу;
4. roadmap определяет порядок дальнейшей миграции.