Introduction to ClassMate
Relevant source files
The following files were used as context for generating this wiki page:
ClassMate is a production-grade, AI-powered lecture recording and meeting assistant system designed for scalability, supporting over 100,000 users. It provides a comprehensive solution for capturing audio, generating real-time transcriptions using AI, and producing intelligent study materials such as summaries, flashcards, and quizzes.
The system utilizes a hybrid scalable architecture that combines cross-platform client applications (Flutter mobile and PWA web) with a containerized backend stack. This stack leverages FastAPI for high-performance API delivery and Celery with Redis for distributed background processing of heavy AI workloads.
Sources: README.md:3-8, PROJECT_STRUCTURE.md:3-5, PROJECT_STRUCTURE.md:143-152
System Architecture
ClassMate employs a multi-layered architecture designed to separate concerns between user interface, business logic, and heavy computational tasks.
High-Level Component Flow
The diagram below illustrates the flow of data from the client applications through the backend services and processing workers.
The recording pipeline captures audio at the client level, uploads it to the FastAPI backend, and queues transcription tasks to distributed Celery workers using Whisper models.
Sources: README.md:10-27, PROJECT_STRUCTURE.md:166-174, docker-compose.prod.yml:71-118
Core Components
1. Frontend Applications
- Mobile App (Flutter): Provides the primary interface for audio capture, session management, and viewing AI-generated notes. It uses Riverpod for state management and Go Router for navigation.
- Web App (PWA): A JavaScript-based Progressive Web App that enables real-time transcription via WebSockets and browser-based recording.
Sources: PROJECT_STRUCTURE.md:113-122, web_app/src/main.js:3-15
2. AI Backend (FastAPI)
The backend serves as the central orchestrator, handling RESTful API requests, WebSocket connections for live updates, and identity bridging between Firebase and the internal PostgreSQL database.
Sources: README.md:13-15, PROJECT_STRUCTURE.md:124-127
3. AI Workers (Celery)
Background workers handle the most resource-intensive tasks:
- Transcription: Uses Whisper models for speech-to-text.
- Diarization: Identification of different speakers within a session.
- Study Assistant: A LangChain-powered agent that generates study guides, quizzes, and flashcards.
Sources: PROJECT_STRUCTURE.md:129-133, ai_backend/agents/study_assistant.py:47-60
Key Features and Services
Study Assistant Agent
The StudyAssistantAgent utilizes LangChain and OpenAI models to transform raw transcripts into educational content.
| Feature | Description | Key Method |
|---|---|---|
| Q&A | Answers questions based on lecture content using vector memory. | ask_question() |
| Flashcards | Generates JSON-formatted flashcards for study. | generate_flashcards() |
| Quiz Generation | Creates multiple-choice questions with explanations. | generate_quiz() |
| Study Guide | Produces comprehensive guides including glossaries and tips. | generate_study_guide() |
Sources: ai_backend/agents/study_assistant.py:73-200
Real-Time Transcription Pipeline
The Web App implements a real-time pipeline using WebSockets to provide immediate feedback during recording.
Infrastructure and Deployment
The project is designed for "infrastructure as code" (IaC) and containerized deployment.
Technology Stack Summary
- Primary Database: PostgreSQL 15 with PgBouncer for connection pooling.
- Object Storage: MinIO (local/dev) or AWS S3 (production) for audio files.
- Cache/Broker: Redis for Celery tasks and rate limiting.
- Orchestration: Docker Compose for local stacks, Kubernetes for production, and Terraform for AWS provisioning.
Sources: infra/README.md:15-28, PROJECT_STRUCTURE.md:143-156, docker-compose.prod.yml:10-70
Configuration Management
Significant environment variables for configuring the system include:
DATABASE_URL: Connection string for PostgreSQL.WHISPER_MODEL_SIZE: Defines the AI model accuracy (e.g.,mediumorlarge-v3).S3_BUCKET_NAME: Target for cloud audio storage.
Sources: infra/README.md:32-38, docker-compose.prod.yml:82-94
Security and Observability
The system implements robust security via Firebase Auth and role-based access control. All database mutations are tracked in audit_logs, and the system supports "Soft Deletes" to prevent immediate data loss. Observability is handled through an integrated stack including Grafana for dashboards, Jaeger for tracing, and Loki for log aggregation.
Sources: README.md:55-68, docker-compose.prod.yml:158-208