services/codemap.md

# backend/services/

## Responsibility
Reusable backend domain and infrastructure services for Firestore persistence, model inference, analytics, risk, memory, and communications.

## Design
- Service modules expose focused functions/classes rather than HTTP routers; route modules call them for domain work.
- `inference_client` and `ai_client` centralize model configuration and DeepSeek access; `wri_service` and `intervention_engine` own risk/intervention logic.
- Firestore-backed modules obtain clients at the service boundary; examples include `curriculum_service`, `memory_service`, and `class_analytics_engine`.
- Other key symbols include `ClassAnalyticsEngine`, `DeterministicResponseCache`, `EmailService`, `QuestionBankService` functions, and `UserProvisioningService`.

## Flow
- `/api/curriculum/...` → `curriculum_routes` → `curriculum_service.get_subjects/get_topics` → Firestore.
- `/api/analytics/class/{class_id}` → `class_analytics_routes` → `get_class_analytics_engine()` / `ClassAnalyticsEngine` → Firestore and WRI classifications.
- `/api/risk/compute` → `risk_router.compute_risk_endpoint` → WRI service → risk response; batch route delegates per-student calculation.
- Chat and generation routes → `inference_client` / `ai_client.get_deepseek_client` → DeepSeek; `memory_service` persists chat turns and summaries in Firestore.
- Quiz Battle routes → `question_bank_service.get_questions_for_battle/cache_session_questions` → Firestore question bank and session cache.
- Class-record upload/report routes → `wri_service` and inference client → Firestore records and computed insights.

## Integration
- Called primarily by `backend/routes/`; selected services are also used by `backend/main.py` and RAG ingestion.
- Firebase Admin/Google Firestore are the persistence boundary; model calls pass through the shared inference/AI clients.
- RAG retrieval/chunk storage lives in `backend/rag/`; services consume RAG results where needed rather than owning Chroma indexing.