Это шаблон Python-сервиса на чистой архитектуре с заменяемым web-слоем, типизированным конфигом, явным dependency wiring и observability через порты.

Что это за проект

• Небольшой референсный сервис со слоями domain/, usecase/, repository/ и adapter/
• Шаблон для сервисов на FastAPI, где FastAPI остается только во внешнем HTTP adapter
• Проект, где конфиг собирается из config/app.yaml, .env и env vars в одно дерево dataclass-конфигов
• Проект, где repository и usecase создаются один раз на старте приложения в composition root
• Проект, где логи, метрики и трейсы скрыты за интерфейсами и могут работать через stdout, файл или OpenTelemetry runtime

Основные идеи

• Clean Architecture и границы SOLID
• Направление зависимостей только внутрь
• Тонкие adapter-слои и явная сборка зависимостей
• Заменяемый HTTP-слой
• Observability без протекания OpenTelemetry во внутренние слои

Быстрый старт

make install
APP_API_TOKEN=local-api-token APP_SIGNING_KEY=local-signing-key make run

Приложение стартует на http://0.0.0.0:8123 и публикует versioned API под /api/v1.

Документация

Гайды

• Правила проекта и ограничения для агента
• Кодстайл проекта для AI-агента
• Чистая архитектура, SOLID, DIP, Protocol и repository
• Логи, метрики и трейсы в этом проекте
• Как чистая архитектура реализована здесь
• План задач и история работ

ADR

• 001 Composition Root and Lifetimes
• 002 Config From YAML and Env
• 003 Observability Via Interfaces
• 004 Versioned HTTP API
• 005 Early FastAPI OTel Instrumentation

Структура проекта

• domain/ - core-сущности и доменные ошибки
• usecase/ - прикладные сценарии и порты
• repository/ - реализации repository
• adapter/config/ - загрузка и модели типизированного конфига
• adapter/observability/ - выбор runtime для logger, metrics и tracer
• adapter/otel/ - OpenTelemetry adapters
• adapter/di/ - composition root и singleton wiring
• adapter/http/fastapi/ - HTTP-схемы, dependencies, middleware и routers
• config/ - YAML-конфиг приложения и локального OTel collector

Для ИИ

Если ты AI-агент и собираешься что-то менять в проекте, сначала прочитай документы в таком порядке:

1. Правила проекта и ограничения агента - обязательные правила работы в этом репозитории
2. Кодстайл проекта для AI-агента - границы слоев, стиль кода и правила зависимостей
3. Как чистая архитектура реализована здесь - практическая карта проекта и типовые сценарии изменений
4. Чистая архитектура, SOLID, DIP, Protocol и repository - базовые архитектурные принципы и примеры
5. Логи, метрики и трейсы в этом проекте - читать перед любыми изменениями в observability, middleware и runtime wiring
6. ADR в docs/ - читать релевантные решения перед изменением архитектуры или startup wiring
7. План задач и история работ - понять, что уже сделано, что отложено и какие ограничения были зафиксированы

Перед началом работы:

• Определи, в каком слое будет изменение: domain/, usecase/, repository/ или adapter/
• Убедись, что зависимости идут только внутрь
• Не тащи FastAPI и OpenTelemetry во внутренние слои
• Сначала изучи существующий код в нужной директории, потом вноси изменения
• Если задача затрагивает архитектурное решение, сначала сверяйся с ADR и проектными правилами

Запуск и команды

• Для локального запуска нужны APP_API_TOKEN и APP_SIGNING_KEY
• make run запускает приложение локально
• make run-otel запускает приложение с локальными OTel endpoints из env vars
• make pre-commit запускает ruff, mypy и pytest
• make compose-up поднимает приложение и локальный LGTM stack через Docker Compose