# 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. Верхнеуровневая карта ```text 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-плоскостью: ```text 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: ```text external document ↓ schema validation ↓ parser / transport model ↓ value validation ↓ mapper ↓ canonical model ↓ handler / feed / service ``` REST и WebSocket могут иметь независимые transport pipelines, но до передачи downstream обязаны сходиться в одну source-independent Canonical Model. **Текущее размещение:** ```text app/src/market_data/acquisition/ ``` **Текущий активный результат:** Production Runtime для Trades Feed завершён в Build 060.25. ### 4.2. Validation, Canonicalization and Data Quality **Назначение:** - проверять структуру внешних документов; - проверять допустимость значений; - нормализовать время, числовые значения и идентификаторы; - преобразовывать transport data в Canonical Models; - контролировать дубликаты, порядок и пропуски; - формировать явные признаки качества и freshness. Эта ответственность сейчас распределена между: ```text 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. **Текущее основное размещение:** ```text 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. **Текущее основное размещение:** ```text 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. Правила зависимостей Разрешённое основное направление: ```text 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 и локальные решения фиксируются в: ```text docs/migrations/build__architecture.md docs/migrations/build_.md docs/decisions/ ``` При конфликте: 1. фактический код и тесты определяют текущее поведение; 2. принятый Build architecture document определяет локальное решение; 3. настоящий документ определяет целевую границу; 4. roadmap определяет порядок дальнейшей миграции.