docs/architecture.md

AI InterviewMentor — Architecture Overview

System Architecture

Browser (React SPA)
    │
    ▼
HF Spaces Docker Container (port 7860)
├── FastAPI (Python 3.11)
│   ├── /api/auth/*        → Custom JWT auth (jose + bcrypt)
│   ├── /api/batches/*     → Batch/class management
│   ├── /api/topics/*      → Topic CRUD + unlock control
│   ├── /api/upload        → CSV question bank ingestion
│   ├── /api/sessions/*    → Session detail + reports
│   ├── /api/instructor/*  → Dashboard + student analytics
│   ├── /api/student/*     → Student dashboard
│   ├── /interview/*       → LangGraph interview engine
│   └── / (catch-all)      → React static files (Vite build)
│
├── LangGraph Engine
│   ├── ask_question       → Picks next question from bank
│   ├── evaluate_answer    → Scores: strong | shallow | wrong
│   ├── counter_question   → Probing follow-up for shallow answers
│   ├── summarize          → Compresses conversation every 4 turns
│   └── generate_report    → Final scored feedback JSON
│
└── External Services
    ├── NeonDB (PostgreSQL)
    │   ├── public schema  → App data (users, batches, topics, questions, sessions)
    │   └── checkpointer   → LangGraph state (auto-managed)
    └── OpenRouter API     → MiniMax 2.7 model

Tech Stack

Layer	Technology
Frontend	React 18 + Vite + TypeScript + Tailwind CSS v3 (dark theme only)
Backend	FastAPI (Python 3.11)
AI Orchestration	LangGraph (state machine with checkpointing)
Database	NeonDB (PostgreSQL) — app data + LangGraph checkpoints
AI Gateway	OpenRouter → MiniMax 2.7
Auth	Custom JWT (jose + bcrypt) — no third-party auth
Deployment	Single Docker container on Hugging Face Spaces (port 7860)

Key Design Decisions

1. Single container deployment — React static build served by FastAPI, no split deployment
2. Same-origin API calls — No CORS needed, browser hits FastAPI directly
3. Two DB schemas — public for app data, checkpointer for LangGraph state
4. Token budget control — Summarize every 4 turns, ~700 token ceiling per LLM call
5. session_id = thread_id — Natural scoping between DB sessions and LangGraph state
6. CSV-to-DB question ingestion — No file storage needed (no S3/R2)
7. Custom JWT only — Supabase/Firebase explicitly banned (hackathon rules)

Database Schema

Tables

• users — id, full_name, email, password_hash, role (student|instructor), batch_id
• refresh_tokens — id, user_id, token_hash, expires_at
• batches — id, name, instructor_id, class_code (auto-generated)
• topics — id, batch_id, name, is_unlocked, order_index
• questions — id, topic_id, question_text, difficulty (easy|medium|hard)
• interview_sessions — id, student_id, topic_id, status, score, feedback (JSONB)

Relationships

instructor (user) → creates batches → has topics → has questions
student (user) → joins batch via class_code → takes interview_sessions on topics

Auth Flow

• Access token: HS256 JWT, 15min expiry, sent in Authorization: Bearer header
• Refresh token: 7-day expiry, bcrypt-hashed in DB, sent as httpOnly cookie
• Route protection: get_current_user dependency extracts JWT → require_instructor / require_student role guards

LangGraph Interview Flow

START → ask_question → [wait for student answer] → evaluate_answer
                                                        │
                              ┌──────────────────────────┼──────────────┐
                              ▼                          ▼              ▼
                       counter_question            ask_question    generate_report → END
                              │                    (or summarize
                              ▼                     every 4 turns)
                       evaluate_answer

• 8 turns max or question bank exhausted → generate_report
• Counter-questions fire once per shallow answer (no double-countering)
• Summarize node compresses messages every 4 turns to keep token usage flat

Frontend Architecture

• Routing: React Router with ProtectedRoute wrapper
• State: Zustand stores — authStore (JWT + user), interviewStore (session state)
• API layer: Single apiFetch wrapper with auto-refresh on 401
• Pages: Login, Signup, StudentDashboard, Interview, Report, InstructorDashboard, Upload, StudentDetail

Scope Boundary (Not In V1)

Voice input, email notifications, leaderboard, certificates, question bank editor UI, light theme, multi-instructor batches.