# 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 → sast → тагирование → deploy staging
- Резервное копирование: pg_dump + object storage snapshot.
- Логи и екзек в контейнер в кулифае, метрики в графане

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

## 9. Безопасность и секреты
- Секреты в ENV (environment secrets в CI).
- Валидация входящих данных, шифрование конфиденциальных данных

## 10. Мониторинг и логирование
- Prometheus метрики через prometheus-fastapi-instrumentator
- Логирование через стандартный Python logging
- Базовый healthcheck endpoint

## 11. Тестирование
- Unit tests - тестируют бизнес логику (entities, factories, invariants)
- E2E - тестируют весь user flow через TestApiGateway
- Интеграционные тесты для взаимодействия с хранилищем