Flipped Exam PoC — Technical Specification

**Status:** Proof of concept for internal testing. Not for official exam use.

#

Purpose

This document summarizes the technical setup of the Flipped Exam PoC: an exam format where students act as examiners interviewing an AI “student” configured by the course teacher.

#

Stack

- **App:** FastAPI (async), Python 3.10+
- **AI:** Azure AI Foundry (Claude), via AnthropicFoundry client
- **DB:** SQLite (WAL), aiosqlite
- **Auth:** Azure AD (Entra ID) JWT
- **Deploy:** Docker + Kubernetes

#

Main Flows

1. **Professor** defines exam templates in the admin dashboard (subject, level, topics, custom instructions, time limits).
2. **Student/Examiner** selects an exam from the dropdown, enters name/email, starts the session. The AI responds as a “student” according to the template.
3. **Session** runs with optional soft/hard time limits; sessions auto-end after the configured max (default 4 hours) if not ended manually.
4. **Admin** can view sessions, grade them, and export transcripts.

#

Key Endpoints

- `POST /api/exam/session/start` — Start exam (requires template_id + examiner).
- `POST /api/chat` — Send message and stream AI reply (exam session enforced server-side).
- `POST /api/exam/session/{id}/end` — End exam.
- Admin: `/api/admin/templates`, `/api/admin/exams`, grading, logs.

#

Docs in This Repo

- **Full technical overview:** `docs/TECHNICAL_OVERVIEW.md` — architecture, components, DB, auth, patterns.
- **Azure auth:** `docs/AZURE_AUTH_SETUP.md`
- **AI interview grading:** `docs/AI_INTERVIEW_GRADING.md`
- **README:** Project root — quick start, features, deployment.

#

Configuration

See `.env.example` for required variables (Azure Foundry endpoint, API key, auth, etc.). For production, set `AZURE_KEY_VAULT_URL` to load secrets from Azure Key Vault (see `app/config.py`). Database and tables are created on first run; a POC exam template is seeded automatically.