Tech Stack

Основной стек

Компонент	Технология	Версия	Обоснование
Backend	Python + FastAPI	3.12 / 0.111+	Async, типизация, экосистема AI
Database	PostgreSQL	16	Надёжность, JSON, расширения
Queue	PG (SKIP LOCKED)	—	Нет отдельного брокера, см. ADR-0001-Use-Postgres-As-Queue
Cache	Redis	7+	Sessions, hot cache
Vector	pgvector (старт)	0.7+	Внутри PG, достаточно для MVP
Container	Docker + Compose	—	Изоляция, воспроизводимость
Process Mgr	pm2 (уже есть)	—	Уже настроен на серверах
Frontend	Telegram (пока)	—	Web UI в Phase 3

LLM Routing

Выбор модели по уровню сложности и стоимости:

Уровень задачи	Модель	Агенты	Cost/1M tokens
Стратегия	Claude Opus 4.6	Agent-CEO, сложные аналитические	$$$
Аналитика	Claude Sonnet 4.6	Directors, Agent-Judge, Agent-MarketResearcher	$$
Рутина	Claude Haiku 4.5	Executors, classification, Agent-CompetitorScout	$

• Модель указывается в roles/*.yaml для каждого агента
• Override per-task возможен через payload.model_override
• Fallback: если основная модель unavailable → Sonnet (кроме Codex-critical задач)

Анти-стек

Что мы НЕ используем и почему:

Технология	Почему нет
n8n / Zapier	Vendor lock-in, нет контроля над логикой, не масштабируется, debugging nightmare
LangChain	Избыточные абстракции, leaky abstractions, лишняя зависимость
LangGraph	Переусложнено для MVP, state machine overhead
CrewAI / AutoGen	Не контролируем оркестрацию, magic > explicit
MongoDB	PostgreSQL покрывает все кейсы (JSON, vector, queue)
RabbitMQ / Kafka	PG SKIP LOCKED достаточно при нашей нагрузке (<1000 tasks/day)
Kubernetes	Overkill для 2 серверов, operational complexity

Принцип: каждая зависимость = обязательство. Добавляем только когда PG / Python / стандартная библиотека не справляются.

Observability Stack

Фаза	Решение
MVP (сейчас)	Собственная таблица runs + FastAPI /admin/dashboard
Phase 2	stdout → journald → Loki, basic Prometheus + Grafana
Phase 3	OpenTelemetry, structured logging, alerting

Переход к внешним tools при > 1GB/месяц логов. До этого — собственный dashboard.

См. Observability для деталей.

Secrets Management

Фаза	Решение
MVP	.env на сервере (не в git), chmod 600
Phase 2	SOPS + age для шифрованных секретов в git
Phase 3	HashiCorp Vault (когда команда > 1 человек)

Правило: секреты НИКОГДА не в git, не в логах, не в task payload.

CI/CD

Developer push
  → GitHub Actions (или Gitea CI)
    → ruff (linting)
    → mypy (type checking)
    → pytest (tests)
    → build Docker image
    → deploy to staging
    → manual promote → production

Pre-commit hooks: ruff check, mypy --strict, pytest -x.

Repo Structure (synth-brain)

synth-brain/
├── api/            # FastAPI routes
├── agents/         # Agent runner, context assembly
├── roles/          # *.yaml role definitions (prompts, tools, budgets)
├── tools/          # Tool implementations
├── policy/         # PolicyEngine, validators
├── queue/          # Worker loop, task management
├── memory/         # RAG, embedding, Librarian logic
├── obs/            # Observability, logging, metrics
├── migrations/     # Alembic SQL migrations
├── tests/          # pytest
├── docker-compose.yml
├── Dockerfile
└── pyproject.toml

Связанные документы

• System-Overview — общая архитектура
• ADR-0001-Use-Postgres-As-Queue — обоснование PG queue
• Observability — мониторинг и логирование
• Policy-Layer — security enforcement