ExamTwin

Build a faithful digital twin of a real exam, practise it under realistic conditions, and turn every attempt into a better next mock.

ExamTwin is an adaptive exam-preparation platform created for OpenAI Build Week. It helps students organise university exams, attach the material that defines each exam, describe its structure and rules, run a focused mock session, and retain results for future feedback and adaptation.

The product is deliberately exam-centred:

• a Subject is a lightweight category such as Quantum Physics;
• an Exam owns its context files, blueprint, scenario, timing, scoring rules, attempts, feedback and statistics;
• a Class shares either a whole Subject or selected Exams with a group;
• an Attempt is an archived mock run with answers, score, duration and feedback.

Current status

The repository contains a working, API-backed P0 product, the complete P1 artifact pipeline, and an opt-in P2 grounded-AI loop. Demo mode remains available for visual review, while normal mode persists the complete core flow in PostgreSQL.

Area	Status
Authentication and profile	Implemented in the API and frontend flows
Subject CRUD	Implemented
Nested Exam CRUD	Implemented
Exam data, blueprint, scenario and rules editor	Persisted through the API with optimistic configuration versions
Exam Run simulation	Backend-generated mock, durable attempt, autosave, reload/resume and immutable submit
Personal statistics and analytics	analytics.v2, canonical observations, versioned snapshots, data-quality gates, trends, readiness and adaptive.v2 implemented
Library publishing and cloning	Implemented with safe public snapshots and independent private clones
Class CRUD, membership and progress	Implemented with owner-only aggregate analytics, small-group suppression, comparable exam scope and experiment events
PostgreSQL models and migrations	Implemented through D3, including observations, snapshots, taxonomy, shadow results and cohort events
Artifact ingestion and retrieval	Implemented: private upload, parsing, chunking, embeddings and owned-exam vector retrieval
Vertex AI generation and evaluation	Implemented with gemini-3.5-flash when APP_VERTEX_PROJECT is configured; deterministic fallback remains available
Background worker pipeline	Implemented with durable Dramatiq/Redis jobs and restart-safe retries

The UI distinguishes the deterministic fallback from Vertex AI generation. AI questions are grounded in retrieved chunks, retain source citations, and use prior weak-topic evidence to adapt later mocks.

Product preview

All product images below were captured from the running local application in the native browser at a laptop/desktop responsive breakpoint. Each screenshot includes the complete page width; no interface sections are cropped or reconstructed.

Dashboard (updated local capture)

The home view keeps the next preparation action prominent and shows the student’s current exam context. This screenshot was freshly captured from the local demo at a wide desktop viewport.

Data-science analytics

The analytics views separate readiness from evidence confidence and make score movement inspectable over time.

Subjects

Subjects are intentionally simple categories. Exam-specific readiness, dates and content live on Exams instead.

Subject workspace

Each Subject exposes its nested Exams and Classes without becoming a second exam-detail surface.

Exams

The global Exams index provides a cross-subject view and the primary creation entry point.

Exam workspace

Exam Detail is the control centre for data sources, blueprint, scenario, rules and attempt history.

Five-step exam creation

The creation flow separates basics, data, blueprint, generation scenario/rules and final review.

Focused Exam Run

The simulation uses a distraction-free shell and prepares a mock from the configured exam structure.

Exam statistics

Statistics are scoped to an Exam and clearly label the confidence of insights while attempt coverage is still low.

Classes

Classes can be scoped to a complete Subject or a selected group of Exams.

Demo video

Watch the ExamTwin product walkthrough on YouTube: ExamTwin — OpenAI Build Week.

Why ExamTwin

Students usually prepare from fragmented notes, syllabi, rubrics, past papers and generic question banks. Conventional generators may cover the same topic, but they rarely reproduce the actual constraints that shape performance: section order, question types, point distribution, allowed materials, time pressure and grading rules.

ExamTwin treats those constraints as first-class data. Its target feedback loop is:

1. Create a Subject category.
2. Create an Exam inside that Subject.
3. Add past papers, rubrics, notes, learning targets and other context.
4. Review the extracted or manually entered blueprint.
5. Configure scenario and rules such as timing, points, pass mark and penalties.
6. Generate a grounded mock exam.
7. Complete it in the focused Exam Run interface.
8. Archive answers, result and feedback.
9. Use evidence from previous attempts to produce a more useful next mock.

Domain model

User
└── Subject (category)
    ├── Exam
    │   ├── Data sources / context files
    │   ├── Blueprint sections
    │   ├── Generation scenario
    │   ├── Rules and grading notes
    │   └── Attempts
    │       ├── Answers
    │       ├── Result
    │       └── Feedback
    └── Class
        └── All subject exams or selected exams

This boundary prevents Subject pages from accumulating exam-only responsibilities and allows multiple finals, midterms, oral exams or certification attempts to coexist under one course category.

Architecture

Browser
  │
  ├── Next.js 16 / React 19 frontend and BFF
  │     ├── App Router pages
  │     ├── API-backed product state (optional local demo mode)
  │     ├── HTTP-only session cookies and authenticated API proxy
  │     └── focused exam-session layout
  │
  └── FastAPI API
        ├── authentication and JWT lifecycle
        ├── ownership-protected CRUD and attempt lifecycle
        ├── SQLAlchemy async models
        ├── Alembic migrations
        └── PostgreSQL / pgvector

files → object storage → worker → parsing/chunking → embeddings/retrieval
      → Vertex AI grounded generation → mock → evaluation → mastery

Technology stack

Layer	Technology	Responsibility
Web	Next.js 16, React 19, TypeScript, Tailwind CSS 4	Product interface and exam session
API	FastAPI, Pydantic, SQLAlchemy asyncio	Auth, ownership and domain APIs
Database	PostgreSQL 17 with pgvector	Relational records and future vector retrieval
Migrations	Alembic	Versioned database schema
Cache/jobs	Redis and Dramatiq worker	Durable artifact processing and retries
AI	Vertex AI / Google Gen AI SDK	Gemini 3.5 Flash generation, embeddings, evaluation and adaptation
Runtime	Docker Compose	Local PostgreSQL, Redis and API services

Repository layout

.
├── backend/
│   ├── api/app/                 # FastAPI routes, services, models and configuration
│   ├── api/migrations/          # Alembic migrations
│   ├── api/tests/               # Unit and PostgreSQL integration tests
│   ├── worker/                  # Background-worker boundary
│   ├── compose.yaml
│   └── pyproject.toml
├── frontend/
│   ├── src/app/                 # Next.js App Router routes and layouts
│   ├── src/components/          # Shared UI and product shell
│   ├── src/features/            # Auth, subjects, exams, classes and demo state
│   └── public/
├── materials/                   # Product screenshots and submission assets
└── deep-research-report.md      # Product research and rationale

Run locally

Prerequisites

• Node.js ^20.19.0 or >=22.12.0
• npm
• Python 3.11–3.13
• Docker with Docker Compose

Fastest path: frontend demo

The frontend can be explored without the API. Demo entities and attempts are stored in browser localStorage.

cd frontend
cp .env.example .env.local
npm install
npm run dev

Open http://localhost:3000. The example environment enables NEXT_PUBLIC_DEMO_MODE=true, so protected product pages are available for local review.

Full P0 product

From the repository root:

cd backend
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
cp .env.example .env
docker compose -f compose.yaml up -d
alembic upgrade head
uvicorn app.main:app --app-dir api --reload --port 8010

In a second terminal:

cd frontend
npm install
NEXT_PUBLIC_DEMO_MODE=false API_URL=http://127.0.0.1:8010/api/v1 npm run dev

Open http://localhost:3000/register. Product data is stored in PostgreSQL; the browser only keeps HTTP-only session cookies and an active-attempt recovery pointer.

To enable grounded AI, set APP_VERTEX_PROJECT and APP_VERTEX_LOCATION in backend/.env and authenticate with Google Application Default Credentials (gcloud auth application-default login). Without Vertex configuration, the same endpoints deliberately use the deterministic generator/evaluator, making local development and CI reproducible.

Health checks:

GET http://localhost:8010/api/v1/health/live
GET http://localhost:8010/api/v1/health/ready

The complete containerised backend can also be started from backend/:

docker compose up --build

By default Compose exposes the API on port 8010, PostgreSQL on 55432, and Redis on 6379.

Implemented API

All endpoints are prefixed with /api/v1.

Method	Endpoint	Purpose
POST	/auth/register	Create an account
POST	/auth/login	Start an authenticated session
POST	/auth/refresh	Rotate access credentials
POST	/auth/logout	End a session
GET, PATCH	/me	Read or update current user
POST, GET	/subjects	Create or list owned subjects
GET, PATCH, DELETE	/subjects/{subject_id}	Manage one subject
POST, GET	/subjects/{subject_id}/exams	Create or list nested exams
GET, PATCH, DELETE	/exams/{exam_id}	Manage one exam
POST, GET	/subjects/{subject_id}/classes	Create or list classes
GET, PATCH, DELETE	/classes/{class_id}	Manage one class
POST	/exams/{exam_id}/mocks	Generate a deterministic mock
GET	/mocks/{mock_id}	Read a mock without exposing answer keys
POST	/mocks/{mock_id}/attempts	Start or resume an active attempt
GET	/attempts/{attempt_id}	Reload an attempt and saved responses
PUT	/attempts/{attempt_id}/responses/{question_id}	Autosave one response
POST	/attempts/{attempt_id}/submit	Submit and evaluate idempotently
GET	/exams/{exam_id}/attempts	List result history
GET	/exams/{exam_id}/statistics	Read basic exam statistics

The legacy /workspaces contract remains available for compatibility while new product surfaces use Subjects and Exams.

Frontend routes

Route	Experience
/home	Student dashboard
/subjects	Subject categories
/subjects/[subjectId]	Nested exams and classes
/exams	Global exam index
/exams/new	Five-step exam creation
/exams/[examId]	Exam workspace
/exams/[examId]/edit	Edit exam configuration
/exams/[examId]/run	Focused mock simulation
/exams/[examId]/statistics	Exam performance overview
/classes	Class management

Quality checks

Frontend:

cd frontend
npm run lint
npx tsc --noEmit
npm run build

Backend:

cd backend
source .venv/bin/activate
ruff check api
ruff format --check api
mypy
TEST_DATABASE_URL=postgresql+asyncpg://postgres:postgres@127.0.0.1:55432/openai_buildweek pytest
alembic check

PostgreSQL integration tests validate authentication, ownership isolation, CRUD, durable Exam configuration, mock generation, autosave, immutable submission and statistics. The same gates run in .github/workflows/ci.yml.

Privacy and product principles

• Private by default: uploaded study materials remain private unless a user explicitly publishes them.
• Exam fidelity over generic generation: mocks should follow the reviewed blueprint and rules.
• Evidence before adaptation: recommendations should disclose confidence, coverage and recency.
• Human review for high-stakes feedback: generated scoring is study guidance, never an official grade.
• Rights-aware sharing: users must have permission to publish third-party course materials.
• Clear prototype boundaries: simulated or incomplete AI functionality is labelled honestly.

Remaining release work

1. Deploy the complete stack and configure judge credentials.
2. Run the committed judge rehearsal in the final release environment.
3. Freeze the release and capture the submission video.

Further documentation

• Frontend guide
• Backend guide
• Data Science D0–D3 acceptance plan
• Analytics v2 model card
• Judge demo runbook
• Research report

License

No open-source license has been selected. Until one is added, all rights are reserved by the repository owner.