VeritasRAG

Independent services

3

Chunk tokens / overlap

512 / 50

HNSW vectors, pgvector

768-d

Reranked candidates

20 to 5

Key features

Architecture

Three independently deployable services behind a Next.js BFF layer:

Browser
  └── Next.js 16 (Vercel)
        ├── Route Handlers (BFF): cookie management, auth proxy, SSE proxy, upload signature
        └── App Router pages: dashboard, documents, chat, citations

Next.js Route Handlers
  └── Django 5 (Render Web Service)
        ├── Auth: SimpleJWT signup/login/logout/refresh
        ├── Documents: CRUD, Cloudinary signature, status polling
        ├── Chat: session + message persistence, Redis cache-aside, SSE proxy
        ├── Stats: dashboard aggregates (Redis cached)
        └── Celery dispatcher → Redis broker

Celery Worker (Render Background Worker, same Django image)
  └── POST /ingest → FastAPI

FastAPI (Render Web Service, internal-only)
  ├── POST /ingest: extract → chunk → embed → pgvector write
  ├── POST /query: embed → hybrid search → rerank → generate → SSE stream
  └── GET /health

PostgreSQL + pgvector (Neon)  |  Redis (Upstash)  |  Files (Cloudinary)

Ingestion flow

POST /api/documents/ (Django)
  → DOCUMENT record (status = uploaded)
  → Celery task dispatched

Celery: process_document(document_id)
  → FastAPI POST /ingest {document_id, storage_key, file_type}
  → fetch file from Cloudinary
  → extract text → chunk (512t, 50 overlap) → embed (text-embedding-004)
  → write CHUNKS + EMBEDDINGS to pgvector
  → return {chunk_count}
  → DOCUMENT.status = ready

Query flow

user sends message
  → Django: Redis cache check hash(question + doc_ids)
  → cache hit: return in <5ms
  → cache miss: FastAPI POST /query (httpx streaming)
      → embed question (text-embedding-004)
      → pgvector HNSW ANN top-20 + BM25 FTS top-20
      → Reciprocal Rank Fusion merge
      → cross-encoder rerank top-20 → top-5
      → grounding check: all scores < 0.75 → grounding_score = 0.0
      → grounding prompt + gemini-2.0-flash SSE stream
  → Django proxies SSE → Next.js Route Handler → browser
  → on complete: persist MESSAGE + CITATIONS + QUERY_LOG; cache response

Data model

Eight PostgreSQL tables plus pgvector:

• users: UUID PK, email, hashed password, full name.
• documents: user-owned; filename, storage_key, file_type, status, chunk_count.
• chunks: document-scoped; chunk_index, content, token_count, page_number.
• embeddings: one-to-one with chunks; vector(768), model_name. Kept separate so re-embedding with a new model doesn't touch chunk data.
• chat_sessions: user-owned; title, document_ids (jsonb array).
• messages: session-scoped; role, content, retrieval_score, grounding_score, latency_ms, cache_hit.
• citations: message-scoped; chunk_id FK, similarity_score, citation_order.
• query_logs: one observability row per query: question, latency, grounding score, cache hit, model used, low_confidence flag.

Outcome

VeritasRAG combines hybrid vector and keyword retrieval, cross-encoder reranking, intent-aware query routing, streaming SSE generation, multi-layer Redis caching, and strict citation grounding across three Docker-based services. Every answer traces to an exact source chunk with page-level provenance, and each architectural boundary is enforced at both the API and database layers.