# Exam Engine V2

This document defines the new exam architecture that will replace the current mixed quiz/exam implementation over time without breaking the existing flows immediately.

## Goals

- Support a broader question bank for admins and teachers.
- Support automatic, manual, and mixed grading.
- Support text answers, rich writing answers, and audio answers.
- Support section-based exams where each section can follow a different grading strategy.
- Separate the question bank from published exams and student attempts.

## Main Tables

- `exam_banks`: reusable question collections owned by staff.
- `exam_bank_questions`: normalized questions with explicit `question_type`, `response_mode`, and `grading_mode`.
- `exam_bank_question_assets`: attachments such as images, passages, or audio prompts.
- `exam_bank_question_options`: answer choices / matching pairs / ordering items.
- `exams_v2`: the exam container.
- `exam_sections`: section-level grouping for writing, listening, speaking, auto-graded blocks, etc.
- `exam_section_questions`: section/question pivot with score overrides and per-exam settings.
- `exam_attempts_v2`: one attempt per student per exam run.
- `exam_attempt_responses`: per-question responses with auto score, manual score, final score, and teacher feedback.

## Supported Direction

The first V2 release is designed to handle:

- single choice
- multiple choice
- true/false
- matching
- ordering
- fill in the blank
- short text
- essay / writing prompt
- audio prompt
- speaking response
- listening comprehension
- reading comprehension

## Grading Model

- `auto`: choice-based and deterministic questions.
- `manual`: writing and speaking answers.
- `mixed`: passages or grouped prompts that contain both auto-scored and manually reviewed parts.

## Migration Strategy

1. Keep the current quiz engine operational.
2. Introduce V2 schema and models in parallel.
3. Add V2 admin/teacher management screens.
4. Migrate authoring and delivery gradually from the legacy quiz tables to V2.