# 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 архитектура.