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

⚠️ Требования к системе

Версия Python

• ✅ Рекомендуется: Python 3.11
• ❌ Не рекомендуется: Python 3.12+ (может работать некорректно или не работать вовсе)
• ℹ️ Причина: Зависимости от специфичных версий библиотек и API

Используемые библиотеки

• SQLAlchemy — ORM для работы с базой данных
• PyYAML — парсинг YAML-конфигов
• psycopg2-binary — драйвер для подключения к PostgreSQL
• python-dotenv — загрузка переменных окружения
• unidecode — транслитерация
• emoji — поддержка emoji
• requests — HTTP-клиент для внешних API-запросов (tools, dev)
• aiohttp — асинхронный HTTP-клиент для Telegram Bot API
• openai — библиотека для работы с OpenAI API через OpenRouter
• gitpython — работа с Git репозиториями (деплой, обновления)
• telegramify-markdown — конвертация Markdown в Telegram MarkdownV2 формат
• croniter — парсинг и работа с cron выражениями для scheduled сценариев
• pydantic — валидация данных по схемам из config.yaml
• cryptography — генерация самоподписанных SSL-сертификатов для Telegram вебхуков
• pgvector — работа с векторными данными в PostgreSQL для RAG (Retrieval-Augmented Generation)
• python-dateutil — работа с датами и временными интервалами (корректная обработка месяцев/годов, края месяцев)

Зависимости для системы деплоя

Утилита деплоя (tools/deployment/) использует дополнительные библиотеки:

• gitpython — клонирование репозиториев, работа с Git операциями
• requests — взаимодействие с GitHub API для создания Merge Requests
• PyYAML — парсинг конфигурации деплоя (config.yaml)
• python-dotenv — загрузка переменных окружения (токены, ключи API)

Операционная база данных

Проект поддерживает две базы данных с возможностью переключения через пресеты:

• SQLite — локальная база для небольших проектов (простота настройки)
• PostgreSQL — промышленная база для продакшна (высокая производительность, масштабируемость)

Основные принципы

• Микросервисная архитектура: каждый сервис работает независимо и самодостаточно
• Event Driven Architecture: все действия инициируются событиями, обрабатываются оркестратором
• Vertical Slice Architecture: каждый сервис независим, получает только нужные данные, не зависит от других сервисов
• Конфигурируемость: вся логика и маршрутизация вынесена в yaml-конфиги
• Слоистая изоляция: четкое разделение ответственности между слоями с иерархией зависимостей
• Взаимодействие между сервисами — только через БД, за исключением редких случаев, когда сервис предоставляет публичные методы (API) для интеграции или специальных задач

Слои и их назначение

Foundation (foundation) — Фундаментальные утилиты

• Назначение: Критически важные утилиты, без которых невозможно создать DI-контейнер и запустить приложение.
• Расположение: plugins/utilities/foundation/
• Может использовать: Только системные библиотеки Python.

Custom Layers — Тематические слои утилит

• Назначение: Утилиты для конкретных технологий или платформ (Telegram, API, базы данных и др.).
• Расположение: plugins/utilities/[layer_name]/ (например, telegram/, ai/, database/)
• Может использовать: Foundation и утилиты внутри своего слоя (не рекомендуется использование из других custom-слоев).

Core (core) — Инфраструктурные утилиты

• Назначение: Утилиты для создания и обработки событий, записи в очередь БД, работы с базой данных. Самый высокий уровень утилит.
• Расположение: plugins/utilities/core/
• Может использовать: Foundation, custom-слои и другие core-утилиты.

Services (services) — Бизнес-сервисы

• Назначение: Основная бизнес-логика приложения, плагины с конкретным функционалом.
• Расположение: plugins/services/
• Может использовать: Foundation, custom-слои и core-утилиты.

📋 Практические примеры использования слоев: Руководство по плагинам

Иерархия зависимостей

Foundation (logger, plugins_manager, settings_manager)
    ↑
┌─────────────────┐
│  Custom Layers  │
│ (telegram, etc) │
└─────────────────┘
    ↑
┌────────┐
│  Core  │
│  ───>  │
└────────┘
    ↑
Services

Правила зависимостей

1. Foundation — используют только системные библиотеки Python
2. Custom Layers — используют foundation и утилиты внутри своего слоя (не рекомендуется использование из других custom-слоев)
3. Core — используют foundation, custom-слои и другие core-утилиты
4. Services — используют foundation, custom-слои и core-утилиты
5. Циклические зависимости ЗАПРЕЩЕНЫ

📋 Примеры зависимостей и практические рекомендации: Руководство по плагинам

Структура директорий

app/                    # Основное приложение
├── application.py      # Точка входа и оркестратор
└── di_container.py     # Контейнер зависимостей

plugins/                # Плагины (утилиты и сервисы)
├── utilities/          # Вспомогательные слои утилит
│   ├── foundation/     # Фундаментальные утилиты (logger, plugins_manager)
│   ├── telegram/       # Telegram утилиты (tg_bot_api, tg_utils)
│   ├── ai/             # ИИ утилиты (ai_client)
│   └── core/           # Core утилиты (event_processor, database_service)
└── services/           # Бизнес-сервисы (плагины)

utils/                  # Системные утилиты
├── database/           # Утилиты для работы с БД (миграции, обновления)
├── updater/            # Утилиты обновления ядра
└── ...                 # Другие системные утилиты

config/                 # Бизнес-конфигурация
└── settings.yaml       # Глобальные настройки системы

📋 Правила создания плагинов и структура папок: Руководство по плагинам

Поток обработки

1. Application (app/application.py) инициализирует foundation утилиты (logger, plugins_manager), собирает информацию обо всех плагинах, регистрирует их, создает контейнер зависимостей и запускает все сервисы.
2. Core утилиты (plugins/utilities/core/) принимают события от внешних источников (например, Telegram Bot API через HTTP, внешние сервисы), обрабатывают их и передают в оркестратор.
3. Оркестратор анализирует события, находит подходящие сценарии и создает задачи для выполнения.
4. Services (plugins/services/) выполняют бизнес-логику через вызовы методов ядра.
5. Взаимодействие между сервисами — только через БД.

📋 Алгоритм инициализации и порядок загрузки: Руководство по плагинам