Architecture Overview
Backend responsibilities
This backend owns:
- user authentication and role-aware access control
- chat orchestration and grounded answer generation
- curriculum retrieval over semantic and lexical indexes
- scraping, reference tracking, and ingestion job orchestration
- wallet reservation, settlement, and transaction logging
- public curriculum browsing and teacher quiz generation
- operational endpoints for admin workflows and metrics
It does not own frontend rendering. The chat UI, admin dashboard, and any mobile clients are consumers of these backend contracts.
Subsystem map
| Area | Current code | Responsibility |
|---|---|---|
| API shell | app/main.py, app/api/router.py, app/api/routers/ |
FastAPI app creation, router registration, HTTP endpoints |
| Auth and request plumbing | app/core/auth.py, app/core/middleware.py |
Supabase JWT validation, admin gating, request IDs, in-memory rate limiting |
| Chat orchestration | app/agents/teacher_agent.py, app/api/routers/chat.py |
Wallet check, retrieval decision, clarification path, answer finalization |
| Retrieval | app/services/retrieval_pipeline.py, app/services/gpt_mini.py, app/services/llm.py |
Translation, hybrid retrieval, reranking, grounded answer generation |
| Ingestion | app/api/routers/admin.py, app/services/hybrid_ingestion.py, app/services/embedding_service.py, app/services/ingestion_handoff.py |
PDF extraction, canonicalization, hybrid index creation, job lifecycle |
| Scraping | app/api/routers/scraping.py, app/services/scrapers/ |
Source discovery, metadata validation, reference persistence, handoff orchestration |
| Wallet and billing | app/api/routers/wallet.py, app/services/wallet_reservation.py |
Token reservation, settlement, top-up, expense logging |
| Data assets | db/bootstrap.sql, db/migrations/ |
Tables, RLS, JWT hooks, lexical search RPC, storage bucket setup |
| Verification | tests/, .github/workflows/ |
Unit tests, router tests, Promptfoo evals, Postman sync guard, API e2e |
Architectural style
The codebase is mostly organized as thin routers plus service modules, but the current implementation is still pragmatic rather than fully abstracted:
- services call Supabase, Pinecone, and OpenAI directly
- dependency wiring is centralized in
app/core/dependencies.py - ingestion work is started from HTTP requests rather than a separate job runner
- LangGraph is used for the teacher chat state machine, but most orchestration remains plain Python
See the focused pages for runtime, data model, retrieval, ingestion, billing, and integration surfaces.