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. Верхнеуровневая карта

```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_<number>_architecture.md
docs/migrations/build_<number>.md
docs/decisions/
```

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

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