Real-time lecture engagement platform powered by Convex.

• Live transcription display (AssemblyAI Universal Streaming)
• AI-powered Q&A (Gemini 2.5 Flash)
• Teacher-triggered comprehension quizzes (AI-generated from transcript content since last quiz)
• "I'm lost" signals with spike detection
• QR code join for students
• Session notes export (PDF)

• Convex - Real-time database and backend platform
• Google Gemini 2.5 Flash - AI model for Q&A, quiz generation, and session summaries
• AssemblyAI Universal Streaming - Real-time speech-to-text transcription (~300ms latency)
• Token Company - Prompt compression API for reduced token costs

• React 19 - UI framework
• TanStack Router & Start - Type-safe routing and SSR
• TailwindCSS 4 - Utility-first CSS framework
• Framer Motion - Animation library
• Lucide React - Icon system
• Vite 7 - Build tool and dev server
• TypeScript 5 - Type-safe JavaScript
• Vitest - Unit testing framework
• qrcode - QR code generation for session join
• jsPDF - PDF export for session notes

You'll need accounts with:

• Convex - Real-time backend
• AssemblyAI - Speech-to-text API
• Google AI Studio - Gemini API
• Token Company (optional) - Prompt compression

1. Install dependencies:

   npm install

2. Copy environment template:

   cp .env.example .env.local

3. Start dev servers:

   npm run dev

   This starts both Convex backend and frontend dev server concurrently.

These must be set in the Convex Dashboard under Settings > Environment Variables, not in local .env files.

Transcription uses AssemblyAI's Universal Streaming v3 API, which provides:

• Real-time streaming (~300ms latency) directly from browser to AssemblyAI
• No agent infrastructure - browser connects via temporary tokens from Convex
• Audio processing - AudioWorklet resamples microphone audio to 16kHz PCM
• Automatic scaling - handles 100+ concurrent streams with auto-scaling

1. Teacher clicks "Start Transcription"
2. Browser requests temporary token from Convex (validates session is live)
3. Browser connects directly to AssemblyAI WebSocket with token
4. Microphone audio is resampled to 16kHz and streamed as raw PCM binary
5. AssemblyAI sends back partial and final transcripts
6. Final transcripts are saved to Convex via mutation

No separate transcription agent deployment needed.

Quiz generation uses a synchronous request/response contract via generateAndLaunchQuiz(). The backend enforces a per-session in-flight lock so duplicate launches are rejected while one generation is running. Generation is fail-closed: if AI generation, parsing, or validation fails, no quiz is launched and the teacher receives an explicit error.

To prevent transcript gaps across consecutive quizzes, generated quizzes are timestamped at generation start.

The app deploys to Cloudflare Pages with automatic GitHub integration:

• Push to main triggers automatic deployment
• Convex backend deploys via npx convex deploy

See SPEC.md for full technical specification.