Architecture Overview

RAG Chat follows a modern full-stack architecture with a React frontend and Convex backend.

System Diagram

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│                 │     │                 │     │                 │
│  React Frontend │────▶│  Convex Backend │────▶│   OpenRouter    │
│   (Vite + TS)   │◀────│   (Real-time)   │◀────│   (AI Models)   │
│                 │     │                 │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌─────────────────┐
                        │                 │
                        │  Vector Store   │
                        │  (Embeddings)   │
                        │                 │
                        └─────────────────┘

Components

Frontend (React + Vite)

• TanStack Router: Type-safe client-side routing
• Convex React: Real-time subscriptions and mutations
• shadcn/ui: Pre-built accessible UI components
• Tailwind CSS: Utility-first styling

Backend (Convex)

• Schema: Typed database tables for files, chunks, threads, and messages
• Functions: Queries, mutations, and actions for all operations
• RAG Pipeline: Document parsing, chunking, and vector embedding
• AI Agent: Orchestrates retrieval and response generation

External Services

• OpenRouter: Provides access to various AI models (GPT-4, Claude, etc.)
• Convex Vector Search: Built-in vector similarity search

Data Flow

Document Upload Flow

1. User uploads a file via the frontend
2. File is stored in Convex file storage
3. Parser extracts text content based on file type
4. Text is split into chunks
5. Each chunk is embedded and stored in the vector index

Chat Flow

1. User sends a message
2. Message is stored and triggers the AI agent
3. Agent performs vector search to find relevant chunks
4. Relevant context is included in the AI prompt
5. AI generates a response with citations
6. Response streams back to the frontend in real-time