add readme.md

RFC.md

@@ -0,0 +1,90 @@
+# 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