Project Structure Analysis
Relevant source files
The following files were used as context for generating this wiki page:
ClassMate is a comprehensive AI-powered meeting assistant application organized as a monorepo. It features a scalable, hybrid architecture designed to support over 100,000 users by combining a cross-platform mobile application, a progressive web application (PWA), and a robust backend capable of high-intensity AI processing.
The project is architected to separate frontend client logic (Flutter and JavaScript) from heavy-lifting AI services (FastAPI and Celery). It utilizes a modern infrastructure stack including Docker for containerization, Kubernetes for orchestration, and Terraform for cloud-based resource provisioning on AWS.
Sources: PROJECT_STRUCTURE.md:3-8, README.md:3-6
Architecture Overview
The system follows a distributed architecture where mobile and web clients interact with a centralized "Control Plane" via a Traefik Gateway. Heavy-duty tasks such as audio transcription and note generation are offloaded to asynchronous workers.
System Components
| Component | Technology | Role |
|---|---|---|
| Mobile App | Flutter / Dart | Native audio capture, local storage, and UI. |
| Web App | PWA / JavaScript | Real-time transcription and dashboard access. |
| AI Backend | FastAPI / Python | API orchestration, user management, and task queuing. |
| AI Workers | Celery / Redis | Asynchronous Whisper transcription and AI note generation. |
| Infrastructure | Docker / AWS / K8s | Container orchestration and cloud resource management. |
Sources: PROJECT_STRUCTURE.md:120-143, README.md:10-25
The following diagram illustrates the high-level data flow and service interactions within the ClassMate ecosystem:
Diagram shows the flow from client requests through the gateway to backend services, task queues, and persistent storage layers.
Sources: README.md:10-25, PROJECT_STRUCTURE.md:155-160
Directory Structure and Module Analysis
The repository is organized into distinct top-level directories that isolate the concerns of different platforms and infrastructure layers.
Frontend Platforms
- mobile_app/: Contains the Flutter source code. It follows a feature-based module structure (onboarding, recording, sessions, etc.) and utilizes Riverpod for state management.
- web_app/: A Progressive Web App (PWA) that provides real-time transcription via WebSockets. It includes an
index.htmlentry point and asrc/main.jsfor handling recording logic and WebSocket communication.
Backend and AI
- ai_backend/: The core API server built with FastAPI. It handles database operations via SQLAlchemy and provides services for transcription and notes.
- ai_workers/: Dedicated Celery workers that process background tasks. Specifically, the
transcription_worker.pyandnotes_worker.pyhandle the AI-heavy lifting. - shared_contracts/: Contains Pydantic models used to ensure consistent data structures between the backend and workers.
Sources: PROJECT_STRUCTURE.md:11-105, web_app/src/main.js:1-15
Infrastructure and Deployment
ClassMate provides multiple deployment pathways, ranging from local development to production-grade cloud environments.
Local Development (Docker Compose)
The infra/docker/ directory contains configurations for running the entire stack locally. Key services include:
- PostgreSQL: Primary relational database (version 15).
- Redis: Serves as both a cache and a message broker for Celery.
- MinIO: Provides an S3-compatible object storage layer for audio files.
- Nginx: Acts as a reverse proxy for routing traffic.
Sources: infra/README.md:18-30, docker-compose.prod.yml:14-110
Cloud Infrastructure (Terraform)
The Terraform configuration in infra/terraform/ defines an AWS-based environment. It creates a VPC with public and private subnets, security groups for service isolation, and managed instances for data persistence.
Diagram represents the AWS infrastructure topology including VPC segmentation and managed data services.
Sources: infra/terraform/main.tf:16-160, infra/README.md:55-75
Deployment Configuration Summary
| Resource | Service / Configuration | File Reference |
|---|---|---|
| Database | PostgreSQL 15 (RDS in Prod) | infra/terraform/main.tf:101 |
| Object Storage | S3 (Production) / MinIO (Local) | infra/terraform/main.tf:167, docker-compose.prod.yml:55 |
| Reverse Proxy | Nginx / Traefik | infra/docker/nginx.conf, README.md:11 |
| Compute | EC2 / Kubernetes | infra/terraform/main.tf:205, infra/README.md:37 |
Data Flow and Recording Pipeline
The project implements a complex pipeline for processing audio data from the point of capture to final AI-generated notes.
- Capture: The Mobile or Web app captures audio. The web app specifically uses the
MediaRecorderAPI to send chunks via WebSockets. - Ingestion: The FastAPI backend receives audio data and stores it in object storage (MinIO or S3).
- Processing: A transcription task is queued in Redis. A Celery worker picks up the task and processes the audio using the Whisper model.
- Finalization: Once transcribed, the notes service generates summaries, which are then stored in PostgreSQL and synced back to the clients.
Sources: PROJECT_STRUCTURE.md:162-172, web_app/src/main.js:84-115
Summary
ClassMate's project structure is designed for high scalability and modularity. By segregating frontend clients, backend orchestration, and AI workers into a monorepo, the project maintains a clear separation of concerns while sharing critical data contracts. The infrastructure-as-code approach via Terraform and Docker ensures consistent environments across development and production, supporting the complex requirements of real-time AI audio processing.