Control Plane
Relevant source files
The following files were used as context for generating this wiki page:
The Control Plane serves as the central orchestration and routing layer for the ClassMate application. It is responsible for managing incoming traffic, enforcing security policies, and directing requests to the appropriate backend services or frontend components. Within the hybrid scalable architecture of ClassMate, the Control Plane ensures that the system can handle significant user loads while maintaining high availability and security.
The core components of the Control Plane include the Traefik or Nginx API Gateway, the FastAPI backend which handles logic and routing, and various security middlewares that protect the system from unauthorized access and malicious activity.
System Architecture
The Control Plane acts as the entry point for all client requests, bridging the gap between the Flutter Mobile App and the internal data and scaling layers.
The diagram shows the Flow of requests from the client through the Control Plane to the underlying data services.
Sources: README.md:14-25, PROJECT_STRUCTURE.md:120-125
Core Components
The Control Plane is comprised of several critical infrastructure and application services that manage the lifecycle of a request:
| Component | Description |
|---|---|
| Traefik / Nginx | Acts as the API Gateway/Reverse Proxy, handling SSL termination and routing. |
| FastAPI Backend | The primary application logic layer providing RESTful endpoints and WebSocket connectivity. |
| Security Layer | Implements rate limiting, request validation, and identity management via Firebase or JWT. |
| Web Dashboard | The frontend administrative and user interface served via the gateway. |
Sources: README.md:27-32, infra/README.md:21-27, docker-compose.prod.yml:128-142
Traffic Management and Routing
The Control Plane manages traffic using a multi-service Docker setup or Kubernetes orchestration. In production environments, Nginx or Traefik handles the routing of traffic to the classmate_api service.
Routing Logic
The system routes traffic based on URL patterns:
/api/v1/: Directed to the FastAPI backend for processing./health: Used for system monitoring and health checks./ws/: Handles real-time WebSocket connections for live updates and transcription.
Sources: infra/README.md:155-160, PROJECT_STRUCTURE.md:140-145, docker-compose.prod.yml:128-142
Service Configuration
In the production environment, the Control Plane services are defined with specific resource limits and scaling capabilities.
api:
image: classmate_api
deploy:
resources:
limits:
memory: 1G
cpus: "2"
Sources: docker-compose.prod.yml:68-100
Security and Governance
A critical function of the Control Plane is enforcing security at the perimeter. This is implemented through multiple layers of middleware within the backend service.
Rate Limiting
The Control Plane enforces per-IP rate limiting to prevent DDoS attacks and API abuse. Different tiers are applied based on the sensitivity of the endpoint.
| Endpoint Pattern | Limit | Window |
|---|---|---|
/auth/login | 10 requests | 60 seconds |
/api/v1/ai/ | 30 requests | 60 seconds |
/api/v1/transcribe | 10 requests | 60 seconds |
/ (General) | 200 requests | 60 seconds |
Sources: ai_backend/core/security.py:44-52
Request Validation and Hardening
The Control Plane sanitizes all incoming inputs and inspects requests for suspicious patterns, such as SQL injection or Cross-Site Scripting (XSS).
The flow of request validation within the Control Plane security middleware.
Sources: ai_backend/core/security.py:157-190
Security Headers
The following headers are injected by the Control Plane to harden the client-side environment:
- X-Content-Type-Options:
nosniff - X-Frame-Options:
DENY - Content-Security-Policy: Restricts sources for scripts, styles, and connections.
- Strict-Transport-Security: Enforced in production for mandatory HTTPS.
Sources: ai_backend/core/security.py:112-145
Observability and Monitoring
The Control Plane integrates with an observability stack to track the health and performance of the routing layer.
- Traefik Dashboard: Provides real-time visibility into active routes and backend health.
- Prometheus/Grafana: Tracks metrics such as request latency, CPU/Memory usage of the API, and error rates.
- Loki/Jaeger: Handles log aggregation and distributed tracing for requests passing through the Control Plane.
Sources: README.md:33-35, docker-compose.prod.yml:146-235
Conclusion
The Control Plane is the backbone of the ClassMate infrastructure, ensuring that user requests are safely and efficiently routed to the backend AI workers and databases. By centralizing security, routing, and observability, the Control Plane enables the system to scale horizontally to support over 100,000 users while maintaining robust protection against external threats.