Это шаблон 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 во внутренние слои

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

```bash
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`.

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

### Гайды

- [Правила проекта и ограничения для агента](AGENTS.md)
- [Кодстайл проекта для AI-агента](docs/CODESTYLE.md)
- [Чистая архитектура, SOLID, DIP, Protocol и repository](docs/CLEAN_ARCHITECTURE_RU.md)
- [Логи, метрики и трейсы в этом проекте](docs/OBSERVABILITY_RU.md)
- [Как чистая архитектура реализована здесь](docs/PROJECT_GUIDE_RU.md)
- [План задач и история работ](tasks.md)

### ADR

- [001 Composition Root and Lifetimes](docs/001-composition-root-and-lifetimes.md)
- [002 Config From YAML and Env](docs/002-config-yaml-plus-env.md)
- [003 Observability Via Interfaces](docs/003-observability-via-interfaces.md)
- [004 Versioned HTTP API](docs/004-versioned-http-api.md)
- [005 Early FastAPI OTel Instrumentation](docs/005-fastapi-otel-early-instrumentation.md)

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

- `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. [Правила проекта и ограничения агента](AGENTS.md) - обязательные правила работы в этом репозитории
2. [Кодстайл проекта для AI-агента](docs/CODESTYLE.md) - границы слоев, стиль кода и правила зависимостей
3. [Как чистая архитектура реализована здесь](docs/PROJECT_GUIDE_RU.md) - практическая карта проекта и типовые сценарии изменений
4. [Чистая архитектура, SOLID, DIP, Protocol и repository](docs/CLEAN_ARCHITECTURE_RU.md) - базовые архитектурные принципы и примеры
5. [Логи, метрики и трейсы в этом проекте](docs/OBSERVABILITY_RU.md) - читать перед любыми изменениями в observability, middleware и runtime wiring
6. [ADR в `docs/`](docs/001-composition-root-and-lifetimes.md) - читать релевантные решения перед изменением архитектуры или startup wiring
7. [План задач и история работ](tasks.md) - понять, что уже сделано, что отложено и какие ограничения были зафиксированы

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

- Определи, в каком слое будет изменение: `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