RekomenciBackend/RFC.md

Rekomenci fluon RFC

Архитектура. (Всё как завещал дядюшка Боб...)

Проект следует чистой архитектуре дядюшки Боба.

RFC-PROOD: Архитектура Recomenci Fluon

Статус: PROOOD Дата: 23 ноября 2025 Автор: prod 39

1. Краткое описание

Цель.

Описать целевую архитектуру, границы ответственности компонентов, модель разработки и деплоя для проекта рекомендаций и предсказаний зарплат (далее — проект)

RFC определяет интерфейсы для API, операционные требования и переходный план

2. Мотивация

• Упорядочить архитектуру для масштабируемости, тестируемости и повторяемости ML-экспериментов
• Обеспечить безопасный и предсказуемый деплой
• Определить контракты между web/API, ML-сервисом и хранилищем данных

3. Область и не-включения

Включено:

• Архитектура сервисов (web_api, ml)
• Хранилища: PostgreSQL, S3(далее object storage)
• CI/CD, контейнеризация и инвентори infra: Docker Compose
• Метрики, логирование, мониторинг базовой обработки ошибок

Не включено:

• Подробный дизайн интерфейсов UI
• Исследовательские ML-эксперименты (детальные датасеты/фичи) — описан процесс интеграции

4. Цели и критерии приёмки

Цели:

• Стабильный REST/HTTP API для вакансий и предсказаний
• Стабильный и масштабируемый REST/HTTP API, утилизирующий ML алгоритмы

5. Высокоуровневая архитектура

• Web API (web_api): HTTP-сервис, инкапсулирующий бизнес логику. Интегрируется с ML-сервисом
• ML сервис (ml): HTTP-сервис, инкапсулирующий ML бизнес логику
• PostgreSQL + pgvector - основное хранилище данных
• Инфра: Docker Compose для локальной разработки; Coolify для CI/CD

Коммуникация:

• HTTP REST между web_api и ml; опционально gRPC / WebSocket в будущем
• Хранение данных в PostgreSQL + pgvector, хранение файловых данных в S3

Входные/выходные схемы должны быть описаны в формате OpenAPI

5.1. Домены приложения

• Resume: управление резюме пользователей, история версий, эмбеддинги, предикты зарплаты
• Vacancy: каталог вакансий с эмбеддингами для поиска похожих
• User: пользователи, профили, аутентификация
• Auth Identity: методы аутентификации (email/password)
• Notification Device: регистрация устройств для уведомлений

5.2. Флоу создания резюме и предикта

1. Пользователь создает резюме через Gateway (AddResumeInteractor)
2. Gateway сохраняет резюме в хранилище и возвращает ответ
3. В фоне запускается ResumePredictionInteractor:
   • Генерирует эмбеддинг резюме через ML Service (модель эмбеддинга)
   • Сохраняет эмбеддинг в хранилище
   • Ищет подходящие вакансии по векторному сходству (HNSW индекс, cosine similarity >= 0.5)
   • Фильтрует и сортирует до 50 наиболее релевантных вакансий
   • Запрашивает предикт зарплаты и рекомендуемые навыки через ML Service (алгоритм предикта)
   • Сохраняет предикт в хранилище

5.3. Структура хранилища

• Users: пользователи, профили
• Resumes: резюме с версионированием (up_resume_id, down_resume_id)
• Resume Embeddings: векторные представления резюме (384 измерения)
• Resume Predictions: предикты зарплаты и рекомендуемые навыки
• Resume Experience/Education/Projects: опыт, образование, проекты
• Vacancies: вакансии с зарплатами и требованиями
• Vacancy Embeddings: векторные представления вакансий (384 измерения)
• Key Skills: словарь навыков для автокомплита (GIN индекс с pg_trgm для ILIKE поиска)

7. Деплой и CI/CD

• Локально: Docker Compose (just up/build)
• Staging/Prod: Coolify
• CI pipeline: lint → build images → full tests → push образ → deploy staging
• Резервное копирование: pg_dump + object storage snapshot.

8. Миграции данных и схем

• Использовать alembic для миграций схем PostgreSQL.
• Использовать вспомогательные скрипты для выгрузки датасета в хранилище

9. Безопасность и секреты

• Секреты в ENV (environment secrets в CI).
• Валидация входящих данных, шифрование конфиденциальных данных

10. Мониторинг и логирование

• Логирование через стандартный Python logging
• Базовый healthcheck endpoint
• Логи можно посмотреть в Coolify (см. креды в Readme.md)
• Доступны дашборды в графане с метриками контейнеров, бека, мль

11. Тестирование

• Unit tests - тестируют бизнес логику (entities, factories, invariants)
• E2E - тестируют весь user flow, а также интеграцию с ml