API Reference Overview 🚀

Welcome to the Gifty Technical API Reference. Our system is built using a layered architecture, where each component has a clear area of responsibility.

Interaction Architecture

Documentation Sections

🕹 API Playground

Interactive Swagger UI console for testing endpoints in the browser (Localhost / Production).

📦 Data Models

Description of Pydantic schemas and SQLAlchemy models. This section defines the data structures transferred between frontend and backend, as well as how they are stored in the database.

⚙️ Services

The system's business logic. Services coordinate the work of repositories and external integrations to solve high-level tasks (e.g., product ingestion flow or recommendation logic).

🗄 Repositories

The data access layer. Direct interaction with the database via SQLAlchemy. Repositories encapsulate complex SQL queries and vector searches.

🌐 Public API

Interfaces for the external frontend: feedback forms (leads), team lists, and recommendation generation.

🔌 Integrations & Weeek

Integration with Weeek for task management: internal endpoints for the bot and public proxies for documentation.

🛡️ Auth API

Session management and login via OAuth 2.0 (Google, Yandex, VK).

📊 Analytics API

A secure proxy layer for retrieving product metrics from PostHog and technical data from Prometheus/Loki.

🔐 Internal API

Interfaces for internal needs: worker management, manual parser execution, product batch ingestion, and AI scoring tasks.