Getting Started

To run this application:

pnpm install
pnpm run start

Linting & Formatting

This project uses Biome for linting and formatting. To run both linter & formater just run:

pnpm run check:fix

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                                    FRONTEND                                         │
│                         (React + TanStack Router + Vite)                            │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│  ┌──────────────────┐    ┌───────────────────────┐    ┌─────────────────────────┐   │
│  │   Auth0Provider  │    │  ConvexReactClient    │    │   TanStack Query        │   │
│  │   (auth state)   │    │  (real-time sync)     │    │   (data caching)        │   │
│  └────────┬─────────┘    └───────────┬───────────┘    └────────────┬────────────┘   │
│           │                          │                              │               │
│           └──────────────────────────┼──────────────────────────────┘               │
│                                      │                                              │
│  ┌───────────────────────────────────┴────────────────────────────────────────┐     │
│  │                            chat.tsx                                        │     │
│  │  ┌────────────────────┐   ┌──────────────────┐   ┌─────────────────────┐   │     │
│  │  │ useQuery()         │   │ useMutation()    │   │ useChat()           │   │     │
│  │  │ • getConversations │   │ • createWith...  │   │ • sendMessage()     │   │     │
│  │  │ • getMessages      │   │ • addUserMessage │   │ • messages state    │   │     │
│  │  └────────┬───────────┘   └────────┬─────────┘   └──────────┬──────────┘   │     │
│  └───────────┼────────────────────────┼────────────────────────┼──────────────┘     │
│              │                        │                        │                    │
└──────────────┼────────────────────────┼────────────────────────┼────────────────────┘
               │                        │                        │
               │ WebSocket              │ WebSocket              │ HTTP POST
               │ (real-time)            │ (mutations)            │ /api/chat
               ▼                        ▼                        ▼
┌──────────────────────────────────────────────────┐  ┌──────────────────────────────┐
│                  CONVEX BACKEND                  │  │   TANSTACK START SERVER      │
│              (Real-time Database)                │  │      (api/chat.ts)           │
├──────────────────────────────────────────────────┤  ├──────────────────────────────┤
│                                                  │  │                              │
│  ┌─────────────────┐    ┌──────────────────────┐ │  │  ┌────────────────────────┐  │
│  │   AUTH CONFIG   │    │      QUERIES         │ │  │  │    streamText()        │  │
│  │   (Auth0 JWT)   │    │  • getConversations  │ │  │  │    google/gemini-2.0   │  │
│  └─────────────────┘    │  • getMessages       │ │  │  └───────────┬────────────┘  │
│                         │  • getConversation   │ │  │              │               │
│  ┌─────────────────┐    └──────────────────────┘ │  │   onFinish() │               │
│  │   MUTATIONS     │                             │  │              ▼               │
│  │  • createWith   │    ┌──────────────────────┐ │  │  ┌────────────────────────┐  │
│  │    FirstMessage │    │   HTTP ACTIONS       │ │◄─┼──│ POST /saveAssistant    │  │
│  │  • addUserMsg   │    │  (http.ts)           │ │  │  │      Message           │  │
│  │  • updateTitle  │    │  /saveAssistantMsg   │ │  │  └────────────────────────┘  │
│  └─────────────────┘    └──────────────────────┘ │  │                              │
│                                                  │  └──────────────────────────────┘
│  ┌─────────────────┐    ┌──────────────────────┐ │                 │
│  │ INTERNAL        │◄───│  addAssistantMessage │ │                 │
│  │ MUTATIONS       │    │  (no auth check)     │ │                 │
│  └─────────────────┘    └──────────────────────┘ │                 │
│                                                  │                 │
├──────────────────────────────────────────────────┤                 │
│                    DATABASE                      │                 │
│  ┌────────────────────────────────────────────┐  │                 │
│  │  ┌──────────┐  ┌──────────────┐  ┌───────┐ │  │                 │
│  │  │  users   │◄─│conversations │◄─│message│ │  │                 │
│  │  │          │  │              │  │       │ │  │                 │
│  │  │ • token  │  │ • userId     │  │• role │ │  │                 │
│  │  │ • name   │  │ • title      │  │• text │ │  │                 │
│  │  │ • email  │  │ • model      │  │• meta │ │  │                 │
│  │  └──────────┘  └──────────────┘  └───────┘ │  │                 │
│  └────────────────────────────────────────────┘  │                 │
└──────────────────────────────────────────────────┘                 │
                                                                     │
┌────────────────────────────────────────────────────────────────────┼───────────────┐
│                            EXTERNAL SERVICES                       │               │
│  ┌────────────────────────┐                    ┌───────────────────┴───────────┐   │
│  │        AUTH0           │                    │    GOOGLE AI (Gemini 2.0)     │   │
│  │  • User authentication │                    │    • LLM inference            │   │
│  │  • JWT tokens          │                    │    • Streaming responses      │   │
│  │  • OAuth flow          │                    │                               │   │
│  └────────────────────────┘                    └───────────────────────────────┘   │
└───────────────────────────────────────────────────────────────────────────────────-┘

Data Flow

Flow	Path	Description
Auth	User → Auth0 → Convex	JWT-based authentication via Auth0Provider
Real-time queries	Frontend ↔ Convex (WebSocket)	Conversations & messages sync in real-time
User messages	Frontend → Convex mutation	createWithFirstMessage or addUserMessage
LLM request	Frontend → /api/chat → Gemini API	Streaming chat via Vercel AI SDK
Save AI response	Server → HTTP Action → Internal Mutation	Persists assistant messages with metadata

Tech Stack

• Frontend: React, TanStack Router/Query, Vite, Flowbite, AI SDK (@ai-sdk/react)
• Backend: Convex (BaaS), TanStack Start (SSR/Server Functions)
• Auth: Auth0 with Convex integration
• LLM: Google Gemini 2.0 Flash
• Hosting: Netlify