Skip to content

Integration Surfaces

Client boundaries

This backend exposes contracts for three classes of consumers:

  • end-user chat and profile clients
  • teacher and parent flows using the same API surface
  • internal operators using admin routes

Frontend, admin, and mobile implementations are not documented here. Only the backend contracts they consume are included.

HTTP surface

The current router groups are:

  • /auth for sign-up, sign-in, logout, and password reset
  • /me for authenticated profile reads and updates
  • /chat for streamed or non-streamed grounded answers
  • /curriculum for public subject and textbook browsing
  • /wallet for balance, reservations, top-ups, expenses, and transactions
  • /admin for user management, stats, references, scrape runs, jobs, document operations, and manual upload
  • /scraping for source sync, scrape runs, references, and handoffs
  • /metrics for Prometheus-style and JSON metrics views
  • /quizzes for quiz and teacher assessment generation

Canonical route registration lives in app/api/router.py and app/api/routers/.

Auth contracts

The backend trusts Supabase Auth for identity and validates bearer tokens on each protected request via app/core/auth.py.

Current role handling:

  • role is read from app_metadata.role when present
  • user_metadata.role remains as a compatibility fallback
  • admin access is enforced by require_admin

Storage and search integrations

Backend integration points to external systems are:

  • Supabase Auth admin API
  • Supabase PostgREST table access and RPCs
  • Supabase storage bucket provisioning via SQL migration
  • Pinecone index operations
  • OpenAI chat and embedding APIs

Non-canonical artifacts

The repository also contains:

  • openapi.json
  • postman/collection.json
  • Postman docs and sync checks

These are important integration artifacts, but the code under app/api/routers/ is the canonical backend contract when drift appears.