# Build 016 — Coordinator Layer Architecture

**Статус:** ✅ Accepted

---

# Цель Build

Определить архитектуру нового слоя **Coordinator Layer**, отвечающего за объединение результатов аналитических Engine в единое представление состояния рынка.

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

---

# Архитектурная задача

После завершения Runtime Layer платформа способна:

- зарегистрировать Engine;
- проверить корректность Runtime;
- определить порядок выполнения Engine;
- выполнить все зарегистрированные Engine;
- собрать результаты в единый `RuntimeResult`.

Однако `RuntimeResult` представляет собой лишь совокупность независимых результатов Engine.

Для получения единой аналитической картины рынка необходим отдельный архитектурный слой.

---

# Причина появления Coordinator Layer

Каждый Engine анализирует только собственную область ответственности.

Например:

```text
Trend Engine
        ↓
UP

Structure Engine
        ↓
BULLISH

Wave Engine
        ↓
IMPULSE

Liquidity Engine
        ↓
LOW
```

Каждый вывод корректен в рамках своего Engine.

Однако платформа должна получить единый ответ на вопрос:

> **Каково текущее состояние рынка с учётом всех аналитических компонентов одновременно?**

Эта ответственность не относится к Runtime Layer.

---

# Назначение Coordinator Layer

Coordinator Layer становится следующим архитектурным уровнем после Runtime Layer.

Он получает:

```text
RuntimeResult
```

и формирует:

```text
CoordinatorResult
```

Coordinator отвечает исключительно за согласование результатов аналитических Engine.

---

# Ответственность Coordinator

Coordinator обязан:

- принимать `RuntimeResult`;
- анализировать результаты всех Engine;
- учитывать статус каждого Engine;
- учитывать confidence каждого Engine;
- выявлять подтверждения между Engine;
- выявлять противоречия между Engine;
- оценивать полноту аналитических данных;
- формировать единый `CoordinatorResult`.

Coordinator не изменяет результаты Engine.

Coordinator не выполняет повторный анализ рынка.

---

# Что Coordinator не делает

Coordinator не должен:

- запускать Engine;
- создавать Engine;
- обращаться к Runtime Registry;
- обращаться к Runtime Runner;
- выполнять анализ рыночных данных;
- рассчитывать технические индикаторы;
- принимать торговые решения;
- взаимодействовать с биржей;
- взаимодействовать с Telegram;
- работать с базой данных;
- работать с AutoTrade.

Coordinator является исключительно аналитическим слоем согласования результатов.

---

# Архитектурная схема

```text
Market Data
        ↓
Engine
        ↓
Runtime
        ↓
RuntimeResult
        ↓
Coordinator
        ↓
CoordinatorResult
        ↓
Trading Layer
```

---

# Границы Coordinator Layer

Coordinator располагается между Runtime Layer и будущим Trading Layer.

Runtime отвечает за выполнение Engine.

Coordinator отвечает за согласование результатов.

Trading Layer принимает решения на основании `CoordinatorResult`.

Таким образом каждый слой имеет собственную область ответственности.

---

# Предварительная структура Coordinator Layer

```text
coordinator/

├── __init__.py
├── models.py
├── protocol.py
├── exceptions.py
├── validation.py
├── rules.py
└── service.py
```

Каждый компонент имеет самостоятельную область ответственности.

---

# Предполагаемые компоненты

## models.py

Определяет модели Coordinator Layer.

Основной моделью станет:

```text
CoordinatorResult
```

В дальнейшем могут появиться дополнительные модели диагностики и согласования.

---

## protocol.py

Определяет официальный публичный контракт Coordinator Layer.

---

## exceptions.py

Содержит исключения Coordinator Layer.

---

## validation.py

Проверяет корректность входного `RuntimeResult`.

---

## rules.py

Содержит правила согласования результатов Engine.

Именно данный компонент будет определять принципы объединения аналитических выводов.

---

## service.py

Является единственной публичной точкой входа Coordinator Layer.

Получает `RuntimeResult`.

Возвращает `CoordinatorResult`.

---

# Допустимые зависимости

Coordinator может использовать:

```text
Common Layer
        ↓
RuntimeResult
        ↓
Coordinator Models
```

Coordinator не должен зависеть от внутренних компонентов Runtime.

---

# Архитектурные принципы

При проектировании Coordinator подтверждены следующие инженерные принципы.

## Single Responsibility

Coordinator отвечает исключительно за согласование результатов Engine.

---

## Stable Foundation

Coordinator строится поверх полностью завершённого Runtime Layer.

---

## One Source of Truth

Единым результатом работы Coordinator становится `CoordinatorResult`.

---

## Architecture First

Сначала утверждается архитектура слоя.

Только после этого начинается реализация его компонентов.

---

# Architecture Review

Во время архитектурной проверки подтверждено:

- Runtime и Coordinator имеют различные области ответственности;
- отсутствует пересечение обязанностей;
- Runtime остаётся инфраструктурным слоем;
- Coordinator становится аналитическим слоем согласования;
- Trading Layer не зависит от внутренних компонентов Runtime.

Architecture Review завершён успешно.

---

# Architecture Decision Record (ADR)

Принято следующее долгосрочное архитектурное решение.

> Coordinator Layer вводится как самостоятельный архитектурный слой между Runtime Layer и Trading Layer.

Coordinator становится единственным компонентом платформы, ответственным за объединение результатов аналитических Engine.

---

# План реализации Build 016.x

Разработка Coordinator Layer утверждена в следующей последовательности.

```text
016.1
Coordinator Models

        ↓

016.2
Coordinator Protocol

        ↓

016.3
Coordinator Exceptions

        ↓

016.4
Coordinator Validation

        ↓

016.5
Coordinator Rules

        ↓

016.6
Coordinator Service
```

Такая последовательность повторяет архитектурный подход, ранее использованный при построении Runtime Layer.

---

# Итог

Build 016 завершает проектирование нового архитектурного слоя платформы.

В результате утверждены:

- назначение Coordinator Layer;
- область ответственности;
- архитектурные границы;
- место слоя в общей архитектуре;
- структура компонентов;
- последовательность дальнейшей реализации.

После завершения Build архитектура платформы принимает следующий вид.

```text
Common Layer
        ↓
Engine Layer
        ↓
Runtime Layer
        ↓
Coordinator Layer
        ↓
Trading Layer
```

Coordinator Layer официально включён в архитектуру подсистемы **Market Intelligence** и готов к реализации в серии Build **016.x**.