# Архитектура Engine Layer

**Версия:** 1.0

**Статус:** Active

---

# Назначение

Настоящий документ определяет архитектуру слоя аналитических движков (Engine Layer)
подсистемы **Market Intelligence**.

Каждый Engine отвечает только за один аспект анализа рынка и никогда не принимает
торговых решений.

---

# Базовая модель Engine

Каждый Engine состоит из двух независимых частей:

```text
Engine
├── Metadata
└── Logic
```

Разделение Metadata и Logic является обязательным архитектурным правилом.

---

# Metadata

Metadata — неизменяемое архитектурное описание Engine.

Metadata содержит:

- имя Engine;
- версию;
- отображаемое имя;
- назначение;
- зависимости;
- поддерживаемые таймфреймы;
- требования к входным данным;
- архитектурные возможности.

Metadata должна быть доступна без создания экземпляра Engine.

Во время выполнения Engine Metadata никогда не изменяется.

---

# Logic

Logic представляет собой аналитическую реализацию Engine.

Вход:

```text
EngineContext
```

Выход:

```text
EngineResult
```

Logic не должна изменять Metadata.

---

# Обязательная структура Engine

```text
<engine>/
├── metadata.py
└── engine.py
```

---

# Рекомендуемая структура Engine

```text
<engine>/
├── __init__.py
├── metadata.py
├── models.py
├── calculators.py
├── evaluators.py
├── checks.py
├── payloads.py
└── engine.py
```

---

# Допустимые расширения

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

Пример:

```text
wave/
├── metadata.py
├── models.py
├── swing_points.py
├── wave_builder.py
├── impulse_detector.py
├── pullback_detector.py
├── evaluators.py
├── checks.py
├── payloads.py
└── engine.py
```

Уникальная внутренняя структура допускается, если сохраняется Runtime Contract.

---

# Запрещённые зависимости

Engine не должен напрямую зависеть от:

- другого Engine;
- AutoTrade;
- Exchange;
- Telegram;
- Execution;
- Journal;
- базы данных.

Результаты других Engine могут передаваться только через:

```text
EngineContext.dependency_results
```

---

# Разрешённые зависимости

Engine может зависеть от:

- `market_intelligence/common`;
- Runtime Contract;
- собственных внутренних модулей;
- стандартной библиотеки Python.

---

# Главное правило

Внутренняя структура Engine может отличаться в зависимости от сложности предметной области.

Однако для любого Engine обязательны:

- соблюдение Runtime Contract;
- наличие Metadata;
- единая точка входа (`engine.py`).

---

# Заключение

Engine Layer развивается через расширение, а не через изменение Runtime.

Добавление нового Engine не должно требовать изменения Runtime Layer.