API Reference Overview 🚀

Добро пожаловать в технический справочник API Gifty. Наша система построена по слоистой архитектуре, где каждый компонент имеет четкую зону ответственности.

Архитектура взаимодействия

Разделы документации

🕹 API Playground

Интерактивная консоль Swagger UI для тестирования эндпоинтов прямо в браузере (Localhost / Production).

📦 Data Models

Описание Pydantic-схем и SQLAlchemy моделй. Здесь определены структуры данных, которые передаются между фронтендом и бэкендом, а также способ их хранения в базе.

⚙️ Services

Бизнес-логика системы. Сервисы координируют работу репозиториев, внешних интеграций и решают высокоуровневые задачи (например, процесс инжеста товаров или логика рекомендаций).

🗄 Repositories

Слой работы с данными. Прямое взаимодействие с базой данных через SQLAlchemy. Репозитории инкапсулируют сложные SQL-запросы и векторный поиск.

🔌 Integrations & Weeek

Интеграция с Weeek для управления задачами: внутренние эндпоинты для бота и публичные прокси для документации.

🛡️ Auth API

Управление сессиями и вход через OAuth 2.0 (Google, Yandex, VK).

🌐 Public API

Интерфейсы для внешнего фронтенда: формы обратной связи (лиды), список команды и генерация рекомендаций.

📊 Analytics API

Гибкий GraphQL API для получения продуктовых метрик из PostHog и технических данных из Prometheus/Loki.

🔐 Internal API

Интерфейсы для внутренних нужд: управление воркерами, принудительный запуск парсеров, прием партий товаров и задачи для AI-скоринга.