Add architecture package and application skeleton

2026-07-03 21:09:47 +03:00
parent 7d6cc1c83e
commit ce2b263e52
47 changed files with 2377 additions and 53 deletions
@@ -0,0 +1,65 @@
+# ADR 001: Runtime Stack
+
+## Status
+
+Accepted
+
+## Context
+
+AI Orchestrator должен быть:
+
+- независимым от Local LLM Platform;
+- пригодным для долгоживущих task runtime;
+- удобным для строгой типизации контрактов;
+- удобным для async I/O: models, MCP, worker connections, event streams;
+- запускаемым без Docker на локальной машине;
+- переносимым на удаленное окружение, включая `docker-test`.
+
+## Decision
+
+Основной стек:
+
+- язык: Python 3.13+;
+- HTTP API: FastAPI;
+- конфиги и схемы запроса/ответа: Pydantic v2;
+- app settings: `pydantic-settings`;
+- конфиги проекта: YAML;
+- event streaming для UI: SSE как основной transport;
+- worker transport: WebSocket;
+- structured logging: JSON lines через стандартный logging layer и event envelopes;
+- тесты: `pytest` + `pytest-asyncio`;
+- runtime packaging: стандартный `pyproject.toml`.
+
+## Why This Stack
+
+Python хорошо подходит для orchestration-heavy систем, где важнее:
+
+- строгое моделирование состояния;
+- быстрая интеграция с внешними AI/MCP endpoint;
+- асинхронный I/O;
+- прозрачные схемы данных;
+- простая локальная разработка без контейнеров.
+
+FastAPI выбран как delivery adapter, а не как центр архитектуры.
+Доменные модели и application services не должны зависеть от FastAPI.
+
+## Consequences
+
+Плюсы:
+
+- быстрый путь к строгим контрактам;
+- хорошая ergonomics для async adapters;
+- удобный локальный запуск без Docker;
+- понятный переход к PostgreSQL и production deployment.
+
+Минусы:
+
+- нужен дисциплинированный layering, чтобы не “утонуть” в framework-driven code;
+- CPU-heavy задачи должны оставаться вне основного request loop.
+
+## Non-Goals
+
+- локальный Docker как обязательный dev path;
+- тяжелая зависимость от конкретной ORM на уровне domain;
+- framework-first архитектура.
+