codemap.md

# backend/

## Responsibility
FastAPI backend entry point: initializes Firebase/Firestore, authentication, middleware, model clients, and API routes; implements core AI, import, analytics, admin, and automation endpoints in `main.py`.

## Design
- `main.py` combines application bootstrap and legacy/core endpoints; domain routers are included as separate `routes.*` modules.
- `app_lifespan` manages startup/shutdown; Firebase Admin initialization is lazy and supports service-account JSON/file and application-default credentials.
- `AuthenticatedUser`, `get_current_user`, `resolve_required_roles`, and role policies centralize bearer-token verification and authorization; environment variables tune model, upload, cache, and async-task behavior.
- Firestore is accessed through `get_firestore_client`; the schema is code-defined through collection/document paths rather than a standalone schema module.

## Flow
1. Import creates FastAPI `app`; startup validates config and initializes runtime clients.
2. `AuthMiddleware` and `RequestMiddleware` process requests; optional SlowAPI setup installs rate-limit handling.
3. `include_router` mounts domain routers; core routes authenticate/authorize, invoke inference/RAG/analytics helpers, then return typed responses or stream results.
4. Data paths read/write Firestore and model/RAG providers; async generation stores task state for `/api/tasks/{task_id}` polling.

## Integration
- Router modules: `rag`, `admin_model`, `admin`, `curriculum`, `diagnostic`, `video`, `quiz_battle`, `teacher_materials`, `class_records`, `risk`, `tutor_checkin`, `practice`, `try_it_yourself`, `ai_monitoring`, `class_analytics`, `intervention`, `pipeline`, `deepseek_rag`, `at_risk_resolution`, `fun_modules`, `jev`.
- Core routes include `/api/chat`, `/api/chat/stream`, `/api/verify-solution`, `/api/predict-risk`, `/api/learning-path`, `/api/lesson/generate`, `/api/quiz/generate`, account import, class-record upload, admin users, analytics, and `/api/automation/*`.
- Firebase Auth token claims/Firestore `users` provide identity and role data. Other directly used collections include `diagnosticResults`, `classRecordImports`, `normalizedClassRecords`, `classrooms`, `managedStudents`, `riskRefreshEvents`, `riskRefreshJobs`, `riskRefreshStats`, and `classSectionOwnership`.
- Uses `middleware.rate_limiter`, `config.models.yaml`/`config.ai_pricing.py`, `services.*`, `rag.*`, and top-level `analytics.py`/`automation_engine.py`.