Skip to main content
GitaChat is built with a modern, scalable architecture that combines powerful AI technologies with robust web frameworks. The application uses a hybrid approach with semantic vector search, traditional commentary, and AI-generated contextual responses.

​
Architecture Overview

GitaChat follows a clean separation between frontend and backend services: 
┌─────────────────────────────────────────────────────────────┐
│                        Frontend Layer                        │
│  Next.js 15 + TypeScript + Tailwind CSS + TanStack Query   │
│              Clerk Auth + Supabase Client                   │
└────────────────────────┬────────────────────────────────────┘
                         │
                    HTTPS/API
                         │
┌────────────────────────┴────────────────────────────────────┐
│                     Backend API Layer                        │
│          FastAPI + Python + SlowAPI (Rate Limiting)         │
└────────────────────────┬────────────────────────────────────┘
                         │
          ┌──────────────┼──────────────┐
          │              │              │
┌─────────▼─────┐ ┌──────▼──────┐ ┌────▼─────┐
│   Pinecone    │ │   OpenAI    │ │  BGE     │
│ Vector Store  │ │   GPT-4o    │ │ Embedder │
│  (768-dim)    │ │    Mini     │ │  Model   │
└───────────────┘ └─────────────┘ └──────────┘

Frontend Architecture

Server-side rendered React application with client-side query caching and optimistic updates

Backend Architecture

RESTful API with async processing, rate limiting, and connection pooling

Vector Search

Semantic search powered by 768-dimensional embeddings and Pinecone

AI Commentary

Context-aware responses generated by OpenAI GPT-4o-mini

​
Frontend Stack

Next.js 15 + React 19

Framework: Next.js with App Router for server-side rendering and routingKey Features:
  • Server and client components for optimal performance
  • API routes for backend integration (/app/api/route.ts)
  • Static generation for verse pages
  • Image optimization and lazy loading
Entry Point: frontend/app/page.tsx handles the main search interface

TypeScript

Type Safety: Comprehensive type definitions in app/lib/types.ts
export interface VerseData {
  chapter: number;
  verse: number;
  translation: string;
  summarized_commentary: string;
  full_commentary?: string;
  related?: RelatedVerse[];
}

TanStack Query (React Query)

State Management: Handles server state with caching and optimistic updatesImplementation (frontend/app/page.tsx:30-36):
const mutation = useMutation({
  mutationFn: submitQuery,
  onSuccess: (result, variables) => {
    const saved: SavedSearch = { query: variables, result };
    localStorage.setItem(LAST_SEARCH_KEY, JSON.stringify(saved));
  },
});

Tailwind CSS

Styling: Utility-first CSS framework with custom themeCustom Colors:
  • Saffron accent color (#FF6B35)
  • Dark mode optimized palette
  • Responsive design breakpoints

Clerk Authentication

Auth Provider: User authentication and session managementIntegration: @clerk/nextjs for seamless auth in API routes
  • User ID tracking for history
  • Protected routes for bookmarks and notes

Supabase

Database: PostgreSQL for user data persistenceTables:
  • query_history - Search history tracking
  • bookmarks - Saved verses
  • notes - User notes on verses
  • email_subscriptions - Daily email preferences

​
Backend Stack

FastAPI

Python Framework: High-performance async API frameworkMain Application (backend/main.py:77):
app = FastAPI(lifespan=lifespan)
app.add_middleware(SlowAPIMiddleware)
app.add_middleware(CORSMiddleware, ...)
Key Features:
  • Async request handling
  • Pydantic validation
  • Auto-generated OpenAPI docs
  • CORS configuration for web clients

Sentence Transformers (BGE)

Embedding Model: BAAI/bge-base-en-v1.5 for semantic searchConfiguration (backend/config.py:32-33):
EMBEDDING_MODEL_NAME = "BAAI/bge-base-en-v1.5"
EMBEDDING_DIMENSION = 768
Initialization (backend/clients.py:24):
embedding_model = SentenceTransformer(EMBEDDING_MODEL_NAME)
Performance: Top MTEB (Massive Text Embedding Benchmark) scores for retrieval

Pinecone

Vector Database: Managed vector search with 768-dimensional embeddingsClient Setup (backend/clients.py:16-18):
pc = Pinecone(api_key=PINECONE_API_KEY)
index = pc.Index(PINECONE_INDEX)
Storage: 700+ verses with metadata (chapter, verse, translation, commentary)

OpenAI GPT-4o-mini

AI Model: Contextual commentary generationClient Configuration (backend/clients.py:21):
openai_client = OpenAI(api_key=GPT_KEY, timeout=30.0)
Use Cases:
  • Generate contextual commentary (utils.py:34)
  • Summarize traditional commentary (utils.py:12)

SlowAPI

Rate Limiting: Request throttling to prevent abuseImplementation (backend/main.py:16,116):
limiter = Limiter(key_func=get_remote_address)

@app.post("/api/query")
@limiter.limit("30/minute")
async def query_gita(request: Request, query: Query):
    ...

​
Data Flow

Search Query Flow

Step-by-Step Process:
  1. User Input: User submits query in Next.js frontend
  2. Frontend API Route: /app/api/route.ts validates and proxies request
  3. Rate Limiting: Frontend checks rate limit (20/min per client)
  4. Backend Endpoint: FastAPI receives at /api/query (30/min limit)
  5. Embedding: Query encoded with BGE model + instruction prefix
  6. Vector Search: Pinecone returns top 8 semantic matches
  7. Hybrid Ranking: Combines semantic score + keyword matching
  8. AI Commentary: OpenAI generates contextual response
  9. Response: Returns best match + 3 related verses
  10. History: Saves to Supabase if user authenticated

Verse Retrieval Flow

Direct Verse Access:
  1. Request: /api/verse with chapter and verse numbers
  2. Metadata Filter: Pinecone query with exact chapter/verse filter
  3. Response: Returns verse with pre-computed summary
  4. No AI Call: Uses cached commentary for fast response

​
Configuration & Environment

Backend Environment

Required Variables (backend/config.py):
  • PINECONE_API_KEY - Pinecone authentication
  • PINECONE_INDEX - Index name (e.g., “gitachat”)
  • GPT_KEY - OpenAI API key
Performance Tuning:
os.environ["TOKENIZERS_PARALLELISM"] = "false"
os.environ["OMP_NUM_THREADS"] = "1"
torch.set_num_threads(1)

Frontend Environment

Required Variables:
  • BACKEND_URL - Python API endpoint
  • NEXT_PUBLIC_CLERK_* - Clerk auth keys
  • NEXT_PUBLIC_SUPABASE_* - Supabase config
  • RESEND_API_KEY - Email service
  • REPLICATE_API_TOKEN - Image generation

​
Performance Optimizations

Frontend Optimizations

  • TanStack Query caching reduces redundant API calls
  • LocalStorage persists last search for instant back navigation
  • Suspense boundaries for progressive loading
  • Optimistic updates for bookmark/note actions

Backend Optimizations

  • Model pre-loading on startup prevents cold starts
  • Connection pooling for Pinecone and OpenAI
  • Async request handling with FastAPI
  • In-memory cache for all verses (all_verses_cache)

Database Optimizations

  • Pinecone indexes for sub-100ms vector search
  • Supabase connection pooling
  • Metadata filtering reduces query time
  • Pre-computed summaries cached in vectors

AI Optimizations

  • GPT-4o-mini selected for speed/cost balance
  • 500 token limit for commentary generation
  • Temperature 0.7 for consistent quality
  • Timeout protection (30s) prevents hanging requests

​
Deployment Architecture

Frontend Deployment

Platform: Vercel (Next.js optimized)
  • Automatic HTTPS and CDN
  • Edge caching for static assets
  • Serverless API routes
  • Preview deployments for PRs

Backend Deployment

Platform: Railway / Render / Fly.io
  • Container-based deployment
  • Auto-scaling based on traffic
  • Health checks at /health
  • CORS configured for frontend domain

​
Security Considerations

Authentication

  • Clerk handles all auth flows
  • JWT tokens for API authentication
  • Secure session management
  • User data isolation in Supabase

Rate Limiting

  • Frontend: 20 requests/min per client
  • Backend: 30 requests/min per IP
  • 429 status codes for limit exceeded
  • Exponential backoff recommended

Input Validation

  • Pydantic models validate all inputs
  • 500 character query limit
  • Chapter (1-18) and verse (1-78) bounds
  • SQL injection protection via Supabase RLS

API Security

  • Environment variables for all secrets
  • CORS whitelist for allowed origins
  • Timeout protection on external calls
  • Error messages don’t expose internals

Build docs developers (and LLMs) love

Get started for freeTalk to us