# 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 для вакансий и предсказаний
- Горизонтально масштабируемый ML embedding-сервис
- Повторяемый pipeline подготовки данных и обучения


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

Коммуникация:
- HTTP rest-ful между web_api и ml; опционально gRPC в будущем
- Обмен артефактами через object storage и метаданные в PostgreSQL

## 6. Контракты API (предварительно)
- Web API:
  - POST /v1/predict — payload: vacancy/resume; returns: salary_prediction {value, confidence, model_version}.  
  - POST /v1/vacancies — сохраняет вакансию для последующей обработки.  
  - GET /v1/models — список доступных моделей и версий.  
- ML service:
  - POST /infer — принимает фичи/сырой текст, возвращает предсказание и мета.  
  - GET /health, GET /metrics.

Входные/выходные схемы должны быть описаны в OpenAPI (yaml) и поддерживаться CI-валидатором

## 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.  
- Версионировать фичи и контракт входных данных (jsonschema).  
- При изменениях схем: обеспечить миграционные скрипты + миграционный план с откатом.

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

## 10. Мониторинг и логирование
- Логи структурированные (JSON), собираются в централизованный collector (ELK/Prometheus + Grafana для метрик).  
- Метрики: latency, error_rate, throughput, model_drift indicators (distribution shifts), resource usage.  
- Алёрты: SLO/SLA для latency/errors.

## 11. Тестирование
- Unit tests - тестируют бизнес логику
- E2E - тестируют весь user flow