# Medical SBA Question Generator  
## Technical Developer Specification

---

## 1. System Purpose

This application is a web-based system for generating, editing, moderating, and exporting **Single Best Answer (SBA)** exam questions for medical education.

The system integrates:

- structured tutor inputs  
- AI question generation  
- human moderation workflow  
- export to exam platforms  
- uploaded RISR workbook processing for variant generation

AI produces draft content, but all questions require human moderation before export.

---

## 2. Development Environment

### Local Development
- XAMPP  
- Apache  
- PHP  
- MariaDB  
- Vanilla JavaScript  
- Composer  
- PhpSpreadsheet  

### Target Production Environment
- Linux server  
- Apache or Nginx  
- PHP  
- MariaDB  

---

## 3. System Architecture

Browser → PHP web application → MariaDB database → OpenAI API

### Important Design Rule
The OpenAI API key is never exposed to the browser.

All AI requests are made **server-side through PHP**.

---

## 4. Session Model

The system does not currently use user accounts.

Instead it uses **workspace sessions**.

### Workflow
- A `workspace_id` is created  
- Stored in browser `localStorage`  
- All data is stored under that workspace  

This allows the user to refresh the page without losing work.

### UI Note
The workspace remains in use internally but is hidden from the homepage UI.

---

## 5. Core Application Components

## 5.1 Question Generator (Implemented)

Generates new SBA questions from tutor inputs.

### Current Inputs
- specialty
- core condition (optional)
- presentation (optional)
- skills (optional, multi-select)
- summative_formative
- year
- tutor_comments (optional)
- num_questions

### Current Behaviour
- sequential generation
- progressive card rendering
- moderation workflow
- full edit panel
- regeneration support

## 5.2 Variant Generator (Partially Implemented)

### Implemented
- `variant_generator.php`
- `.xlsx` upload
- `upload_risr_file.php`
- PhpSpreadsheet integration
- RISR header validation
- preview table with show/hide toggle
- uploaded question checkbox list
- select all / clear selection
- clicked question detail viewer

### Planned
- variants-per-question input
- batch variant generation job creation
- save generated variants
- reuse moderation and export workflows

---

## 6. Generation Workflow

The main generator works as:

User submits form  
→ `start_generation_job.php` creates job  
→ front end repeatedly calls `generate_next_question.php`  
→ each question is saved and displayed

Generation is sequential rather than full-batch.

---

## 7. Generation Job Model

Generation jobs track the state and metadata of a generation request.

### Current Fields
- id
- workspace_id
- specialty
- condition_name
- presentation
- learning_outcome
- num_questions
- questions_completed
- status
- skills
- summative_formative
- year_level
- tutor_comments
- created_at

### Status Values
- running
- complete

---

## 8. Question Moderation Workflow

Each question has a moderation state.

### Possible States
- Draft
- Done
- Rejected

### Moderation Controls
- Edit
- Mark Done
- Reject
- Regenerate

Only **Done** questions are exported.

---

## 9. Editing System

The edit panel now supports full SBA content editing.

### Current Editable Fields
- title
- stem
- lead_in
- option_a
- option_b
- option_c
- option_d
- option_e
- correct_answer_letter
- justification

### Current UI
- fixed right-side panel
- close button
- reopens on Edit click

### Save Endpoint
`update_question.php`

### Moderation/Edit Alignment Clarification (Current Code)
- Generator and variant save paths now both enforce server-side `correct_answer` derivation from `correct_answer_letter` and options `A-E` (`update_question.php` and `update_question_content.php`).
- Both moderation flows use `update_question_status.php`, and allowed statuses are `Draft`, `Done`, and `Rejected`.
- Both flows now use backend-canonical post-save refresh with `get_question.php` in the save flow.

### Intentional Current Workflow Differences
- Export-ready removal outcome differs by tool:
  - Generator: removing from ready moves question to `Rejected`.
  - Variant: removing from ready moves question back to `Draft`.
- Save interaction differs:
  - Generator uses autosave (plus manual save).
  - Variant uses manual save.
- Answer controls differ:
  - Generator uses an answer-letter select input.
  - Variant uses answer-letter text input and a readonly correct-answer text display.

---

## 10. Export System

## 10.1 Current Implemented Export
`export_done_questions.php`

### Current Behaviour
- exports Done questions only
- limited to current workspace
- warns if there are no Done questions
- outputs CSV aligned to RISR column order

### Important Mapping
- Question text = formatted stem + lead_in
- Stem column = blank
- Comments = tutor_comments
- Examiner notes = blank for RISR export
- Summative/Formative = saved value
- Year = saved `year_level`
- Year of Writing = current year generated in PHP
- Available answers = answer text with `;1.00` / `;0.00`

## 10.2 Planned Export Formats
- real `.xlsx`
- Word
- Blackboard Learn Ultra
- Microsoft Forms

---

## 11. Variant Generator

### Current Flow
Upload → Validate → Optional Preview → Checkbox Selection → Clicked Question Review

### Current Upload Endpoint
`upload_risr_file.php`

### Current Output from Upload Endpoint
- upload status
- header match flag
- preview rows
- question title list
- full question detail data for clicked-row review

### Design Requirement
Must support later variant generation for up to 100 uploaded questions.

---

## 12. Database Schema

The application uses **MariaDB**.

## 12.1 Table: `workspaces`
Stores workspace sessions.

## 12.2 Table: `generation_jobs`
Stores generation job metadata and progress.

## 12.3 Table: `questions`
Stores generated and moderated questions.

### Important Current Fields
- workspace_id
- source_type
- source_question_id
- title
- stem
- lead_in
- option_a to option_e
- correct_answer
- correct_answer_letter
- justification
- specialty
- condition_name
- presentation
- skill
- year_level
- summative_formative
- tutor_comments
- tags
- status
- created_at
- updated_at

---

## 13. API Endpoints

### Main Generation
- `start_generation_job.php`
- `generate_next_question.php`

### Question Retrieval and Editing
- `get_workspace_questions.php`
- `get_question.php`
- `update_question.php`

### Moderation
- `update_question_status.php`
- `delete_question.php`
- `clear_workspace_questions.php`

### Export
- `export_done_questions.php`

### Variant Upload
- `upload_risr_file.php`

#### Purpose
- accept `.xlsx` upload
- save temporary uploaded file
- load workbook with PhpSpreadsheet
- validate headers
- extract preview rows
- return uploaded question titles
- return per-row detail data for clicked review

### Active Endpoint and Schema Clarification
- Active upload endpoint in current code: `app/api/upload_risr_file.php`
- Active export endpoint in current code: `app/api/export_done_questions.php`
- Canonical schema file in current codebase: `exam_questions_schema_UPDATED.sql`
- The following files currently exist as empty placeholders and are not active:
  - `app/services/export_service.php`
  - `app/api/export_risr.php`
  - `app/api/export_moderation_pack.php`
  - `app/services/question_generator.php`
  - `app/services/variant_generator.php`
  - `app/api/upload_risr.php`
  - `database/schema.sql`

---

## 14. Frontend Components

### Main Files
- `public/index.php`
- `public/generator.php`
- `public/variant_generator.php`
- `public/assets/js/generator.js`
- `public/assets/js/variant.js`

### generator.js Responsibilities
- generation form submission
- progress updates
- question rendering
- moderation actions
- edit panel loading
- filter logic
- export readiness display

### variant.js Responsibilities
- upload handling
- preview toggle
- checkbox selection list
- select all / clear selection
- clicked question detail display

---

## 15. AI Prompt System

The system uses two prompt definitions.

- Prompt 1 – SBA Question Generator  
- Prompt 2 – Variant Generator  

### Prompt Responsibilities
- clinical realism  
- distractor quality  
- question structure  
- explanation style  
- variant transformation rules  

---

## 16. Current Feature Status

Implemented:
- Workspace system
- Sequential question generation
- Full SBA editing
- Moderation actions
- Status filters
- Export readiness panel
- RISR-aligned export
- Summative/Formative pipeline
- Year pipeline
- Tutor comments pipeline
- Variant upload page
- Excel upload and reading
- Header validation
- Preview toggle
- Checkbox selection
- Clicked question details

Not yet implemented:
- actual variant generation
- variants-per-question input
- batch variant generation jobs
- variant save-back to database
- export of approved variants

---

## 17. Next Development Steps

Priority features:

1. Add variants-per-question input
2. Create variant generation job workflow
3. Generate variants sequentially
4. Save variants into `questions`
5. Reuse moderation interface for variants
6. Export approved variants

---

## 18. Long Term Enhancements

Possible future improvements:
- duplicate detection
- difficulty scoring
- curriculum coverage analysis
- question bank search
- multi-user authentication