build 039: complete Quotes Feed migration foundation

docs/market_intelligence/engines/architecture.md

@@ -0,0 +1,171 @@
+# Архитектура 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.