System Architecture

EduGap dùng kiến trúc tách lớp: Next.js chịu trách nhiệm trải nghiệm học tập, session SSR và BFF proxy; FastAPI giữ business logic, xác thực, adaptive engine và AI orchestration; Supabase PostgreSQL là data plane cho auth, relational data, pgvector, RLS và RPC.

Runtime topology

flowchart TB
  Browser["Browser: student, mentor, admin"] --> Next["Next.js 16 App Router"]
  Next --> SSR["Supabase SSR session cookies"]
  Next --> Proxy["BFF proxy: /api/v1/[...path]"]
  Proxy --> FastAPI["FastAPI backend: /api/v1/*"]
  FastAPI --> Auth["Supabase JWT + role resolver"]
  FastAPI --> Adaptive["Adaptive Engine"]
  FastAPI --> Chat["LangGraph Socratic Tutor"]
  FastAPI --> Redis["Redis cache / in-memory fallback"]
  Adaptive --> RPC["PostgreSQL RPC submit_attempt_v3"]
  Chat --> RAG["RAG retrieval + citation validator"]
  RAG --> Match["match_slides pgvector RPC"]
  RPC --> Supabase["Supabase PostgreSQL app/audit schemas"]
  Match --> Supabase
  Chat --> Braintrust["Braintrust traces"]

Layer responsibilities

Main request paths

App API path

1. Browser calls frontend/app/api/v1/[...path]/route.ts.
2. BFF reconstructs BACKEND_API_URL/api/v1/{path}.
3. BFF reads Supabase SSR session cookie and injects Authorization: Bearer <access_token>.
4. FastAPI verifies token in src/api/adaptive_routes.py.
5. Route handler performs business logic and returns JSON or SSE.

This keeps browser code from manually managing backend tokens while preserving server-side authorization.

Adaptive practice path

1. Frontend requests /api/v1/adaptive/recommend.
2. Backend loads student_concept_mastery, candidate questions and adaptive_policies.
3. LinUCB scores candidate question arms using [1.0, BKT mastery, normalized Elo].
4. Backend logs adaptive_decisions and returns a single question.
5. Submit goes through /api/v1/adaptive/submit, server-side grading and submit_attempt_v3.

AI tutor path

1. Frontend calls /api/v1/chat, optionally as SSE.
2. Backend loads profile, session history and long-term memory.
3. LangGraph runs analyze -> respond_general/respond_academic -> pedagogical_reflection.
4. Academic responses retrieve course context through RAGService.
5. Citation validation strips or flags unsupported citations before response metadata is returned.

Security boundaries

• Live backend accepts Supabase JWTs, not raw UUIDs or fake tokens.
• Frontend may use NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY; backend app/audit access must use SUPABASE_SECRET_KEY.
• Student routes reject cross-student student_id access.
• Mentor/admin/dev routes use role checks in FastAPI, not UI-only conditions.
• submit_attempt_v3 is granted to service_role after the security migration; browser clients do not execute the RPC directly.
• Academic integrity is enforced in the tutor prompt, graph reflection node and server-side hint/AI signal counting.

Deployment shape