Architecture

The application follows a layered design: Router → Service → Repository → Model, with Pydantic schemas at API boundaries.

General request flow

HTTP Client
    │
    ▼
FastAPI (CORS middleware, SlowAPI rate limiter)
    │
    ▼
API Router  (/api/v1/{module})
    │
    ▼
Service     (business logic)
    │
    ▼
Repository  (SQLAlchemy queries)
    │
    ├──► PostgreSQL  (persistent data, pgvector)
    └──► Redis       (refresh / reset tokens)

RAG query flow

POST /api/v1/rag/query  { query, history[] }
    │
    ▼
Embed query (Gemini, task_type=retrieval_query)
    │
    ▼
pgvector search:  score = 1 - (embedding <=> query_vector)
    │               candidates = RAG_TOP_K × RAG_CANDIDATE_MULTIPLIER
    │               filter: score >= RAG_SIMILARITY_THRESHOLD
    │               sort desc, take RAG_TOP_K
    ▼
Build product context (enriched documents: category stats, discounts, stock)
    │
    ▼
Build prompt:  SYSTEM + Previous conversation (last 6 msgs) + Context + Question
    │
    ▼
Generate answer (Gemini)
    │
    ▼
RAGResponse { answer, sources[], query, history[] }

Inactive products and zero-stock items are excluded from vector retrieval. The client stores history and sends it on the next turn (stateless server; no Redis session for chat).

Prerequisites

• Docker and Docker Compose
• Google AI Studio API key (GEMINI_API_KEY) for RAG features
• Python 3.11+ — only required if you run tests or Alembic locally outside Docker

Getting Started

1. Clone and configure

git clone https://github.com/Donovan-Nudrak/E-Commerce_API_RAG.git
cd E-Commerce_API_RAG
cp .env.example .env

Edit .env and set at minimum:

• SECRET_KEY — long random string for JWT signing. In production (DEBUG=false), use a secure random value (at least 32 characters). The .env.example placeholder is rejected at startup and will prevent the API from running.
• POSTGRES_PASSWORD — database password
• GEMINI_API_KEY — your Gemini API key

Use RAG_EMBEDDING_MODEL=models/gemini-embedding-001 (required format for the Gemini embedding API).

2. Start services

docker compose up -d --build

3. Run migrations

docker compose exec api alembic upgrade head

4. Seed initial data

docker compose exec api python -m app.database.seed

Local URLs

Default admin credentials (seed)

Email:    admin@ecommerce.com
Password: admin1234

These credentials are for local development only. Change them before any public deployment.

Index RAG

TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@ecommerce.com","password":"admin1234"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

curl -s -X POST http://localhost:8000/api/v1/rag/index \
  -H "Authorization: Bearer $TOKEN"

curl -s -X POST http://localhost:8000/api/v1/rag/index/categories \
  -H "Authorization: Bearer $TOKEN"

RAG Module

The RAG module lets customers ask natural-language questions about the catalog. Answers are grounded in retrieved product data; the model is instructed not to invent products or prices.

Design highlights

• Embeddings stored on products.embedding (768 dimensions) via pgvector
• Retrieval uses cosine distance (<=>); similarity score = 1 - distance
• Filtering drops matches below RAG_SIMILARITY_THRESHOLD
• Indexing enriches documents with category counts, discount percentages, low-stock alerts, and category price ranges
• Category blend — 80% product vector, 20% category vector (applied in step 2 of indexing; see below)
• Multi-turn — client sends history: [{role, content}, ...]; server returns updated history (stateless; no server-side chat session)

Retrieval pipeline

                    ┌─────────────────────────────┐
  query embedding   │  SELECT top (K × multiplier)│
        ───────────►│  active, stock > 0,         │
                    │  embedding NOT NULL         │
                    └─────────────┬───────────────┘
                                  │
                    score = 1 - cosine_distance
                                  │
                    ┌─────────────▼───────────────┐
                    │  score >= THRESHOLD ?       │
                    │  sort by score DESC         │
                    │  take RAG_TOP_K             │
                    └─────────────┬───────────────┘
                                  │
                    ┌─────────────▼───────────────┐
                    │  Build context + prompt     │
                    │  Generate with Gemini       │
                    └─────────────────────────────┘

Configurable parameters

Indexing (required order)

1. POST /api/v1/rag/index (admin) — embeds all active products from enriched text documents
2. POST /api/v1/rag/index/categories (admin) — embeds per-category summaries and blends into product vectors

Example index responses:

{ "indexed": 6, "errors": 0, "message": "Reindexed active products." }

{ "categories_processed": 5, "products_updated": 6, "errors": 0 }

RAG endpoints

Multi-turn conversation example

Turn 1 — initial question:

curl -s -X POST http://localhost:8000/api/v1/rag/query \
  -H "Content-Type: application/json" \
  -d '{"query": "what affordable products do you have?", "history": []}'

Example response (abbreviated structure):

{
  "answer": "We have several affordable options:\n\n* **Cotton T-Shirt**: $12.50\n* **Organic Coffee 1kg**: $18.90 (24% off)\n* **Bluetooth Headphones**: $19.99 (33% off)",
  "sources": [
    {
      "id": 3,
      "name": "Cotton T-Shirt",
      "price": "12.50",
      "discount_price": null,
      "stock": 200,
      "category_name": "Clothing",
      "similarity_score": 0.745
    },
    {
      "id": 4,
      "name": "Organic Coffe 1kg",
      "price": "24.90",
      "discount_price": "18.90",
      "stock": 80,
      "category_name": "Food & Beverages",
      "similarity_score": 0.741
    }
  ],
  "query": "what affordable products do you have?",
  "history": [
    { "role": "user", "content": "what affordable products do you have?" },
    { "role": "assistant", "content": "We have several affordable options:..." }
  ]
}

Turn 2 — follow-up using history from turn 1:

curl -s -X POST http://localhost:8000/api/v1/rag/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "do any of those have a discount?",
    "history": [
      {"role": "user", "content": "what affordable products do you have?"},
      {"role": "assistant", "content": "We have several affordable options:..."}
    ]
  }'

The assistant can answer in context (e.g. listing discounted items mentioned earlier). history grows by two messages per turn (user + assistant). Only the last 6 messages are injected into the prompt.

Sample RAGResponse fields

Each sourc