You've already forked RekomenciBackend
ivankirpichnikov
91 lines
4.9 KiB
Markdown
91 lines
4.9 KiB
Markdown
# 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 → push образ → 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
|