Architecture Overview

┌─────────────────────────────────────────────────┐
│                   User                           │
│      (Cloudflare Pages — static files)          │
│   ┌──────────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│   │ Landing page │  │   Chat   │  │ Gurukula │  │ Maharshi │  │
│   │  index.html  │  │ chat.html│  │learning. │  │maharshi. │  │
│   │  (/)         │  │ (/chat)  │  │html(/lrn)│  │html(/... │  │
│   └──────────────┘  └─────┬────┘  └──────────┘  └──────────┘  │
└───────────────────────────┼──────────────────────┘
                            │  POST /api/chat
                            ▼
┌─────────────────────────────────────────────────┐
│          API Layer (GCP Cloud Run)               │
│   ┌─────────────────────────────────────────┐   │
│   │         FastAPI (Python)                │   │
│   │  - Rate limiter (30/min/IP)             │   │
│   │  - CORS locked to frontend domain       │   │
│   │  - Request validation                   │   │
│   │  - Auth (JWT, email/password)           │   │
│   └────────────────┬────────────────────────┘   │
│   ┌────────────────┴────────────────────────┐   │
│   │   Vedic Knowledge Base (BM25 search)    │   │
│   │  DharmicData: Rig/Yajur/Atharva Vedas   │   │
│   │  HuggingFace: Sama Veda, Krishna Yajur  │   │
│   │  (Griffith/Keith translations)           │   │
│   │  Memory-optimized BM25, caps @ 10K/3K   │   │
│   │  ✓ Tried first before web search        │   │
│   └────────────────┬────────────────────────┘   │
│   ┌────────────────┴────────────────────────┐   │
│   │      Web Search (Tavily → Wiki → DDG)   │   │
│   │  Tavily (API key) as primary fallback   │   │
│   └────────────────┬────────────────────────┘   │
│   ┌────────────────┴────────────────────────┐   │
│   │    Context + Prompt + Question           │   │
│   │    sent to Sarvam AI for synthesis       │   │
│   └────────────────┬────────────────────────┘   │
│   ┌────────────────┴────────────────────────┐   │
│   │   Database (Neon Postgres)               │   │
│   │   Users, conversations, history          │   │
│   └─────────────────────────────────────────┘   │
└──────────────────┬──────────────────────────────┘
                   │  Sarvam AI API
                   ▼
┌─────────────────────────────────────────────────┐
│            Sarvam AI (sarvam-105b)               │
│        128K context, hosted by Sarvam AI         │
└─────────────────────────────────────────────────┘

User: "What does Rig Veda say about truth?"

  1. POST /api/chat { message, history }
  2. Check rate limit → reject if over quota
  3. Search Vedic corpus (BM25 over DharmicData + HF Vedas)
  4. If corpus results found → use as context (skip web search)
  5. If not → search web (Tavily → Wikipedia → DuckDuckGo)
  6. Format results + question into prompt
  7. Send prompt to Sarvam AI /v1/chat/completions
  8. Parse response, attach source references
  9. If authenticated, auto-save to conversation history
 10. Return { reply, sources } to frontend
 11. Frontend renders markdown with code block styling
 12. Non-blocking: fetch follow-up suggestions via /api/suggest

User opens /learn in browser

  1. GET /api/learning/courses
  2. Returns 3 tiers: beginner(10), intermediate(12), advanced(14)
  3. User clicks an adhyaya
  4. GET /api/learning/courses/{id}/{idx}?top_k=5
  5. Backend runs BM25 queries from course definition against Vedic corpus
  6. Returns lesson content + real verses with source labels
  7. Frontend renders lesson, objectives, verses, reflection questions
  8. GET /api/pronunciation/terms — key Sanskrit terms with IAST + audio
  9. Quiz generated client-side from lesson content (3-5 questions)
 10. Progress saved to localStorage + syncs to server via PUT /api/learning/progress
 11. Daily reading: GET /api/learning/daily-reading (random corpus verse)