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 для вакансий и предсказаний
• Горизонтально масштабируемый 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