---
description: "Архитектурные паттерны и структура проекта Telegram бота на aiogram"
alwaysApply: true
---

# Архитектура проекта

Этот проект - Telegram бот на **aiogram 3.10.0** с четкой архитектурой и разделением ответственности.

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

```
helper_bot/
├── handlers/          # Обработчики событий (admin, callback, group, private, voice)
│   ├── services.py    # Бизнес-логика для каждого модуля
│   ├── exceptions.py  # Кастомные исключения модуля
│   └── dependencies.py # Dependency injection для модуля
├── middlewares/       # Middleware для cross-cutting concerns
├── utils/            # Утилиты и вспомогательные функции
├── keyboards/        # Клавиатуры для бота
└── filters/          # Кастомные фильтры

database/
├── repositories/     # Репозитории для работы с БД (Repository pattern)
├── models.py         # Модели данных
├── base.py           # Базовый класс DatabaseConnection
└── async_db.py       # AsyncBotDB - основной интерфейс к БД
```

## Архитектурные паттерны

### 1. Repository Pattern
- Все операции с БД выполняются через репозитории в `database/repositories/`
- Каждая сущность имеет свой репозиторий (UserRepository, PostRepository, etc.)
- Репозитории наследуются от `DatabaseConnection` из `database/base.py`
- Используется `RepositoryFactory` для создания репозиториев

### 2. Service Layer Pattern
- Бизнес-логика вынесена в сервисы (`handlers/*/services.py`)
- Handlers только обрабатывают события и вызывают сервисы
- Сервисы работают с репозиториями через `AsyncBotDB`

### 3. Dependency Injection
- Используется `BaseDependencyFactory` для управления зависимостями
- Глобальный экземпляр доступен через `get_global_instance()`
- Зависимости внедряются через `DependenciesMiddleware`
- Для каждого модуля handlers может быть свой `dependencies.py` с фабриками

### 4. Middleware Pattern
- Middleware регистрируются в `main.py` на уровне dispatcher
- Порядок регистрации важен: DependenciesMiddleware → MetricsMiddleware → BlacklistMiddleware → RateLimitMiddleware
- Middleware обрабатывают cross-cutting concerns (логирование, метрики, rate limiting)

## Принципы

1. **Разделение ответственности**: Handlers → Services → Repositories
2. **Асинхронность**: Все операции с БД и API асинхронные
3. **Типизация**: Используются type hints везде, где возможно
4. **Логирование**: Всегда через `logs.custom_logger.logger`
5. **Метрики**: Декораторы `@track_time`, `@track_errors`, `@db_query_time` для мониторинга

## Версия Python

Проект использует **Python 3.11.9** во всех окружениях:
- Локальная разработка: Python 3.11.9 (указана в `.python-version`)
- Docker (production): Python 3.11.9-alpine (указана в `Dockerfile`)
- Минимальная версия: Python 3.11 (указана в `pyproject.toml`)

**Важно:**
- При написании кода можно использовать фичи Python 3.11
- Доступны улучшенные type hints, match/case (Python 3.10+)
- Используйте type hints везде, где возможно
- `@dataclass` доступен (Python 3.7+)

**Структура проекта:**
- Docker файлы находятся в двух местах:
  - `/prod/Dockerfile` - для инфраструктуры (Python 3.11.9-alpine)
  - `/prod/bots/telegram-helper-bot/Dockerfile` - для бота (Python 3.11.9-alpine)
- При обновлении версии Python нужно обновить оба Dockerfile

**Для локальной разработки:**
Рекомендуется использовать `pyenv` для установки Python 3.11.9:
```bash
pyenv install 3.11.9
pyenv local 3.11.9
```

Подробнее см. `docs/PYTHON_VERSION_MANAGEMENT.md`