encoach_backend_new_v3/docs/ENCOACH_USER_STORIES.md

# EnCoach Platform -- Granular User Stories (English Only)

**Document Version:** 2.0
**Date:** April 2026
**Status:** Active -- Ready for Development
**Scope:** English Language Only (General English + IELTS). Math/IT deferred to future phase.
**Audience:** Odoo Developer (full-stack, using Cursor IDE)

---

## Companion Documents

| Document | Version | Purpose |
|----------|---------|---------|
| `ENCOACH_WORKFLOWS_FRONTEND_SRS.md` | v1.1 | Frontend technical specification |
| `ENCOACH_WORKFLOWS_BACKEND_SRS.md` | v1.1 | Backend technical specification |
| `ENCOACH_USER_STORIES_OVERVIEW.md` | v1.0 | High-level overview (superseded by this document for development) |

---

## How to Read This Document

Each user story follows this format:

> **US-[ACTOR]-[NUMBER]: [Title]**
> **As a** [single role], **I want to** [one specific action], **so that** [one clear benefit].

**One story = one function = one testable unit.**

### Actor Prefixes

| Prefix | Actor | Section |
|--------|-------|---------|
| SL | Self-Learning Student | Section 1 |
| ES | Entity/University Student | Section 2 |
| AD | Admin / Teacher | Section 3 |
| PV | Public Verifier | Section 3 (end) |

### Priority Legend

| Priority | Meaning |
|----------|---------|
| **Must Have** | Core functionality. Cannot launch without this. |
| **Should Have** | Important. Can be deferred briefly if needed. |
| **Could Have** | Desirable enhancement. Implement if time permits. |

---

# SECTION 1 -- SELF-LEARNING STUDENT JOURNEY

The complete end-to-end journey of an individual student who registers independently, pays for access, and learns on their own.

---

## 1A. Registration

### US-SL-01: Register a New Account

**As a** self-learning student, **I want to** create an account by providing my name, email, password, and selecting "Self-Learner" as my role, **so that** I can access the platform independently.

**Acceptance Criteria:**
- [ ] Registration page is accessible at `/register` without authentication
- [ ] Form fields: Full Name, Email, Password, Confirm Password, Role (select "Self-Learner"), CAPTCHA
- [ ] Password strength indicator updates in real time (Weak/Medium/Strong)
- [ ] Email uniqueness checked on blur; inline error if taken
- [ ] CAPTCHA must be completed before submission
- [ ] On success, redirect to `/verify-email?email={email}`
- [ ] On validation error, show field-level error messages

**Flow:**
1. Student opens `/register`
2. Fills in all fields, selects "Self-Learner" role
3. Completes CAPTCHA
4. Clicks "Create Account"
5. System creates account, sends 6-digit OTP to email
6. Redirect to email verification page

**Error / Edge Cases:**
- Duplicate email: inline error on blur
- CAPTCHA failure: "Please complete the CAPTCHA"
- Network error: toast "Something went wrong. Please try again."

**SRS Reference:** Frontend 4, Backend 12
**Priority:** Must Have

---

### US-SL-02: Verify Email Address

**As a** self-learning student who just registered, **I want to** enter a 6-digit verification code sent to my email, **so that** the platform confirms I own this email address.

**Acceptance Criteria:**
- [ ] Page shows "We've sent a 6-digit verification code to {email}"
- [ ] 6-digit OTP input auto-focuses first digit, advances focus automatically
- [ ] "Verify" button enabled only when all 6 digits entered
- [ ] On valid OTP: redirect to `/onboarding`
- [ ] On invalid OTP: clear input, show "Invalid verification code. Please try again."
- [ ] On expired OTP: show "This code has expired. Please request a new one."
- [ ] "Resend code" disabled for 60 seconds after each send (countdown shown)
- [ ] Maximum 3 resend attempts; after 3: "Maximum resend attempts reached. Please contact support."
- [ ] Code expires after 15 minutes (countdown timer shown)

**Flow:**
1. Student lands on `/verify-email?email={email}`
2. Checks email for OTP
3. Enters 6 digits
4. Clicks "Verify"
5. On success, proceeds to onboarding wizard

**Error / Edge Cases:**
- Wrong code: input clears, retry allowed
- Code expired: must request new one
- All 3 resends exhausted: contact support
- Browser closed: returns to verification on next login (account still unverified)

**SRS Reference:** Frontend 5, Backend 13
**Priority:** Must Have

---

## 1B. Onboarding

### US-SL-03: Select Learning Goal

**As a** self-learning student, **I want to** select my learning goal (General English, IELTS Academic, or IELTS General Training) in Step 1 of the onboarding wizard, **so that** the platform tailors my experience to my objective.

**Acceptance Criteria:**
- [ ] Step 1 of 4 in the onboarding wizard at `/onboarding`
- [ ] Progress bar shows "Step 1 of 4"
- [ ] Radio card group displays available goals loaded from `GET /api/onboarding/goals`
- [ ] English-related options: General English, IELTS Academic, IELTS General Training
- [ ] Each card has: icon, title, description
- [ ] User must select one goal before clicking "Next"
- [ ] "Back" button is hidden on Step 1

**Flow:**
1. Student lands on onboarding wizard
2. Views available learning goals
3. Selects one goal (e.g., "IELTS Academic")
4. Clicks "Next" to proceed to Step 2

**SRS Reference:** Frontend 6, Backend 14
**Priority:** Must Have

---

### US-SL-04: Set Target Level and Timeline

**As a** self-learning student, **I want to** set my target band/CEFR level and optionally an exam date in Step 2, **so that** the platform knows what I'm aiming for and by when.

**Acceptance Criteria:**
- [ ] Step 2 of 4 in the onboarding wizard
- [ ] For IELTS goals: band score slider 4.0-9.0 in 0.5 steps
- [ ] For General English goals: CEFR level select (A1-C2)
- [ ] Optional exam date picker: "I have an upcoming exam on..."
- [ ] Checkbox: "I don't have a specific exam date" hides the date picker
- [ ] "Back" returns to Step 1 without losing data
- [ ] "Next" proceeds to Step 3

**Flow:**
1. Student sets target band/CEFR level
2. Optionally selects exam date or checks "no specific date"
3. Clicks "Next"

**SRS Reference:** Frontend 6, Backend 14
**Priority:** Must Have

---

### US-SL-05: Set Study Preferences

**As a** self-learning student, **I want to** configure my study hours per week, study mode, and learning style in Step 3, **so that** the platform personalises content delivery to my preferences.

**Acceptance Criteria:**
- [ ] Step 3 of 4 in the onboarding wizard
- [ ] Hours per week: slider, 1-40, default 10. Shows estimated completion time
- [ ] Study mode: radio group -- "Self-study" or "With a teacher"
- [ ] Learning style: checkbox group (multi-select, at least one) -- Visual, Audio, Reading, Mixed
- [ ] "Back" returns to Step 2 without losing data
- [ ] "Next" proceeds to Step 4

**Flow:**
1. Student adjusts study hours slider
2. Selects study mode
3. Selects one or more learning styles
4. Clicks "Next"

**SRS Reference:** Frontend 6, Backend 14
**Priority:** Must Have

---

### US-SL-06: Choose Placement Test Decision

**As a** self-learning student, **I want to** decide whether to take the placement test now or skip it in Step 4, **so that** I can either get an accurate level assessment or start at a default level.

**Acceptance Criteria:**
- [ ] Step 4 of 4 in the onboarding wizard
- [ ] Heading: "Ready to find your level?"
- [ ] Description explains the test (~20-30 minutes)
- [ ] "Take Placement Test Now" button: submits wizard data, navigates to `/student/placement`
- [ ] "Skip for Now" button: shows warning "Without a placement test, we'll start you at B1 (intermediate) level. You can take the test anytime from your dashboard." Submits wizard data, navigates to `/student/dashboard`
- [ ] On submission, account status changes to `activated`
- [ ] All 4 steps of wizard data submitted via `POST /api/onboarding/complete`

**Flow:**
1. Student reads the placement test description
2. Chooses "Take Placement Test Now" or "Skip for Now"
3. Wizard data is submitted
4. Account is activated
5. Redirect to placement test or dashboard

**Error / Edge Cases:**
- Browser closed mid-wizard: data lost, user restarts wizard on next login (account still `unactivated`)
- Skip chosen: default level B1, dashboard banner prompts test later

**SRS Reference:** Frontend 6, Backend 14
**Priority:** Must Have

---

## 1C. Placement Test

### US-SL-07: View Placement Test Briefing

**As a** self-learning student, **I want to** see an overview of the placement test before starting, **so that** I know what to expect (sections, duration, adaptive nature).

**Acceptance Criteria:**
- [ ] Briefing page at `/student/placement`
- [ ] Shows: subject (English), estimated duration (20-30 min), section count (4), adaptive note
- [ ] Dimension breakdown table: Grammar (~30 MCQ, ~8 min), Vocabulary (~20 items, ~5 min), Reading (~10 Q / 2 passages, ~10 min), Speaking (3 prompts, ~5 min)
- [ ] "Begin Test" button starts the test
- [ ] If an active incomplete session exists, "Begin Test" resumes from where the student left off

**Flow:**
1. Student navigates to `/student/placement`
2. Reviews test overview
3. Clicks "Begin Test"
4. System creates CAT session and navigates to test interface

**SRS Reference:** Frontend 7, Backend 15
**Priority:** Must Have

---

### US-SL-08: Take Placement Test -- Grammar Section

**As a** self-learning student, **I want to** answer adaptive grammar questions one at a time, **so that** the system accurately assesses my grammar proficiency.

**Acceptance Criteria:**
- [ ] Full-screen distraction-free interface (no sidebar)
- [ ] Top bar: elapsed timer, section name "Grammar", progress "Question X of ~30"
- [ ] Each question fetched one at a time from backend (no pre-loading)
- [ ] After each answer, next question adapts in difficulty (IRT algorithm)
- [ ] Question types: MCQ (single answer), MCQ (multiple answers)
- [ ] "Previous" button disabled (no going back in CAT)
- [ ] Auto-save every 10 seconds; "Saved" indicator shown
- [ ] When backend returns `section_complete: true`, show transition: "Grammar section complete. Next: Vocabulary" with countdown or "Continue" button

**Flow:**
1. First grammar question appears
2. Student selects answer, clicks "Next"
3. Backend returns next (adapted) question
4. Repeat until section complete
5. Transition screen to Vocabulary section

**Error / Edge Cases:**
- Network loss: auto-save ensures no data loss; resume on reconnection
- Browser close: resume from last save on next login

**SRS Reference:** Frontend 8, Backend 15-16
**Priority:** Must Have

---

### US-SL-09: Take Placement Test -- Vocabulary Section

**As a** self-learning student, **I want to** answer adaptive vocabulary questions, **so that** the system assesses my vocabulary range.

**Acceptance Criteria:**
- [ ] Section name shows "Vocabulary", progress updates
- [ ] Question types: MCQ, gap fill, definition match
- [ ] Same CAT adaptive behaviour as Grammar section
- [ ] Auto-save every 10 seconds
- [ ] On section complete, transition to Reading section

**Flow:**
1. First vocabulary question appears after Grammar transition
2. Student answers adaptive questions
3. Section completes, transition to Reading

**SRS Reference:** Frontend 8, Backend 15-16
**Priority:** Must Have

---

### US-SL-10: Take Placement Test -- Reading Section

**As a** self-learning student, **I want to** read passages and answer comprehension questions, **so that** the system assesses my reading proficiency.

**Acceptance Criteria:**
- [ ] Section name shows "Reading", progress updates
- [ ] Split view: passage on left, questions on right (desktop). Scrollable passage above questions (mobile).
- [ ] Question types: MCQ, True/False/Not Given
- [ ] Passages progress from easy to difficult (CAT adaptation)
- [ ] Auto-save every 10 seconds
- [ ] On section complete, transition to Speaking section

**Flow:**
1. First reading passage and questions appear
2. Student reads passage, answers questions
3. Repeat for second passage
4. Section completes, transition to Speaking

**SRS Reference:** Frontend 8, Backend 15-16
**Priority:** Must Have

---

### US-SL-11: Take Placement Test -- Speaking Section

**As a** self-learning student, **I want to** record spoken responses to 3 prompts, **so that** the system can evaluate my speaking ability via AI.

**Acceptance Criteria:**
- [ ] Microphone permission prompt appears at the start of the section
- [ ] If permission denied: section skipped with note "Speaking section skipped. Your placement will be based on the other three sections."
- [ ] 3 speaking prompts, each showing: prompt text, "Start Recording" button, 60-second countdown
- [ ] During recording: waveform visualiser, "Stop" button
- [ ] After recording: playback controls, "Re-record" (max 1 re-record per prompt), "Submit Recording"
- [ ] Audio uploaded as blob via `POST /api/placement/speaking-upload`
- [ ] On final prompt submission, "Finish Test" button navigates to results page

**Flow:**
1. Microphone permission requested
2. First speaking prompt displayed
3. Student clicks "Start Recording", speaks for up to 60 seconds
4. Clicks "Stop", reviews via playback
5. Optionally re-records once
6. Clicks "Submit Recording"
7. Repeats for prompts 2 and 3
8. Clicks "Finish Test"

**SRS Reference:** Frontend 8, Backend 18
**Priority:** Must Have

---

### US-SL-12: View Placement Results

**As a** self-learning student, **I want to** see my overall CEFR level and per-dimension scores after completing the placement test, **so that** I understand my current proficiency.

**Acceptance Criteria:**
- [ ] Results page at `/student/placement/results?session={id}`
- [ ] Overall CEFR level displayed prominently (e.g., "B2" with coloured badge)
- [ ] Per-dimension scores in a radar chart: Grammar, Vocabulary, Reading, Speaking
- [ ] Score table: Dimension, Score %, CEFR Level, Gap to Target
- [ ] If Speaking evaluation is pending: row shows "Pending" badge, polls `GET /api/placement/speaking-status` every 30 seconds until complete
- [ ] "Continue" button at the bottom navigates to learning path preview

**Flow:**
1. Student lands on results page after test completion
2. Views overall CEFR level
3. Reviews per-dimension breakdown
4. Waits for Speaking evaluation if pending
5. Clicks "Continue"

**Error / Edge Cases:**
- Speaking pending: "Pending" badge with polling
- Network error loading results: retry button

**SRS Reference:** Frontend 9, Backend 15, 17
**Priority:** Must Have

---

### US-SL-13: View Personalised Learning Path Preview

**As a** self-learning student, **I want to** see a personalised learning path based on my placement results BEFORE any payment prompt, **so that** I understand what I will study and can make an informed decision about subscribing.

**Acceptance Criteria:**
- [ ] Learning path preview section on the results page (below scores)
- [ ] Course outline card: estimated duration, module count, study hours per week
- [ ] Skill gap modules listed by priority (largest gap first) with: module name, estimated hours, resource type icons (PDF, Video, Audio, Exercise), difficulty level
- [ ] "View Full Course Plan" button expands the detailed module breakdown
- [ ] This is shown BEFORE any payment prompt (key design principle)

**Flow:**
1. Student views placement results
2. Scrolls down to learning path preview
3. Reviews proposed modules and estimated effort
4. Clicks "Continue" to proceed to payment options

**SRS Reference:** Frontend 9, Backend 15
**Priority:** Must Have

---

### US-SL-14: Choose Payment or Access Option

**As a** self-learning student, **I want to** choose between full subscription, free trial, or skip, **so that** I can start learning immediately or decide later.

**Acceptance Criteria:**
- [ ] Three pricing cards at `/student/placement/access`:
  - "Unlock Full Course" -> navigates to `/student/subscription`
  - "Try Free for 7 Days" -> activates trial, navigates to dashboard
  - "Continue to Dashboard" -> navigates to dashboard with persistent banner
- [ ] Free trial: limited access to first 3 modules only
- [ ] Skip: persistent banner on dashboard "Unlock your personalised course -- Subscribe now"

**Flow:**
1. Student views three pricing options
2. Selects one
3. Proceeds to subscription, dashboard (trial), or dashboard (skip)

**SRS Reference:** Frontend 10
**Priority:** Should Have

---

## 1D. Exam Taking

### US-SL-15: Start an Assigned Exam Session

**As a** self-learning student, **I want to** open an exam that has been assigned to me and enter the distraction-free exam interface, **so that** I can take the exam under controlled conditions.

**Acceptance Criteria:**
- [ ] Full-screen interface at `/student/exam/:examId/session` (no sidebar, minimal header)
- [ ] Top bar: exam title, current section name, section countdown timer, overall progress bar
- [ ] All sections and questions pre-loaded (unlike CAT)
- [ ] First section starts immediately with its countdown timer
- [ ] Auto-save every 10 seconds; "Saved" indicator shown

**Flow:**
1. Student navigates to the exam session
2. Exam loads with all sections
3. First section countdown begins
4. Student starts answering questions

**Error / Edge Cases:**
- Exam not assigned: redirect with error "This exam is not available to you"
- Access window expired: "This exam's access window has closed"

**SRS Reference:** Frontend 17, Backend 25
**Priority:** Must Have

---

### US-SL-16: Answer Listening Questions

**As a** self-learning student taking an IELTS exam, **I want to** listen to audio recordings and answer questions for each Listening part, **so that** my listening comprehension is assessed.

**Acceptance Criteria:**
- [ ] Audio player with play/pause, progress bar, volume control
- [ ] Audio plays once (IELTS standard). No replay unless configured for practice mode.
- [ ] Question types: MCQ (single), MCQ (multiple), gap fill
- [ ] Section timer counts down; warning at 5 min and 1 min remaining
- [ ] "Next" navigates to next question; "Previous" navigates back within the section
- [ ] "Flag for Review" marks the question with a flag icon
- [ ] On timer expiry: answers auto-submit, student moves to next section

**Flow:**
1. Listening section begins, audio plays
2. Student answers questions while listening
3. Navigates between questions
4. Flags uncertain questions
5. Section ends (timer or manual submit)

**SRS Reference:** Frontend 17, Backend 25
**Priority:** Must Have

---

### US-SL-17: Answer Reading Questions

**As a** self-learning student taking an IELTS exam, **I want to** read passages and answer comprehension questions for each Reading part, **so that** my reading comprehension is assessed.

**Acceptance Criteria:**
- [ ] Split view: passage on left, questions on right (desktop)
- [ ] Question types: MCQ, True/False/Not Given, gap fill, matching
- [ ] Section timer with warnings at 5 min and 1 min
- [ ] Previous/Next navigation within section
- [ ] "Flag for Review" available
- [ ] Auto-save every 10 seconds

**Flow:**
1. Reading section begins
2. Student reads passage, answers questions
3. Navigates between questions and passages
4. Section ends (timer or manual submit)

**SRS Reference:** Frontend 17, Backend 25
**Priority:** Must Have

---

### US-SL-18: Complete Writing Tasks

**As a** self-learning student taking an IELTS exam, **I want to** write responses to Writing Task 1 and Task 2 using a rich text editor, **so that** my writing ability is assessed.

**Acceptance Criteria:**
- [ ] Rich text editor with word count displayed
- [ ] Task 1: minimum 150 words (indicator turns red below minimum)
- [ ] Task 2: minimum 250 words (indicator turns red below minimum)
- [ ] Submission is NOT blocked by low word count (student may choose to submit anyway)
- [ ] Section timer with warnings
- [ ] Auto-save every 10 seconds

**Flow:**
1. Writing section begins
2. Student reads Task 1 prompt, writes response
3. Monitors word count
4. Moves to Task 2, writes response
5. Section ends (timer or manual submit)

**SRS Reference:** Frontend 17, Backend 25
**Priority:** Must Have

---

### US-SL-19: Record Speaking Responses in Exam

**As a** self-learning student taking an IELTS exam, **I want to** record spoken responses for each Speaking part, **so that** my speaking ability is assessed.

**Acceptance Criteria:**
- [ ] Same audio recording interface as placement test (US-SL-11)
- [ ] Part 1: Familiar topic questions
- [ ] Part 2: Cue card long turn (1 min prep + 2 min speaking)
- [ ] Part 3: Abstract discussion linked to Part 2 topic
- [ ] Microphone permission prompt
- [ ] Playback and re-record (max 1) per prompt
- [ ] Audio uploaded on submission

**Flow:**
1. Speaking section begins
2. Student records responses for Parts 1, 2, and 3
3. Reviews each recording
4. Submits recordings

**SRS Reference:** Frontend 17, Backend 25
**Priority:** Must Have

---

### US-SL-20: Review and Submit Exam

**As a** self-learning student, **I want to** review a summary of my answers before final submission, **so that** I can ensure I haven't missed any questions.

**Acceptance Criteria:**
- [ ] Review summary page shows per section: answered count, unanswered count, flagged count
- [ ] Flagged questions listed with "Go to Question" links
- [ ] "Submit Exam" button with confirmation dialog: "Are you sure? You cannot change your answers after submission."
- [ ] After submission, navigate to submission confirmation page

**Flow:**
1. Student completes all sections
2. Review summary appears
3. Student reviews flagged/unanswered items
4. Optionally returns to fix answers
5. Clicks "Submit Exam"
6. Confirmation dialog -> final submit

**SRS Reference:** Frontend 17, Backend 25
**Priority:** Must Have

---

### US-SL-21: View Exam Results (Auto-Release)

**As a** self-learning student whose exam has auto-release enabled, **I want to** see my results immediately after submission, **so that** I know my score right away.

**Acceptance Criteria:**
- [ ] Results page at `/student/exam/:examId/results`
- [ ] Overall band score displayed prominently (e.g., "6.5")
- [ ] CEFR equivalent shown
- [ ] Per-skill radar chart and table: Skill, Band, CEFR, Gap to Target
- [ ] Listening and Reading: auto-scored, shown immediately
- [ ] Writing and Speaking: if pending teacher grading, show "Pending Review" with estimated wait time
- [ ] Feedback section: per-question feedback (expandable accordions per section)
- [ ] "Areas to improve" summary: top 3 weakness areas
- [ ] "Download PDF Report" button
- [ ] "View Recommended Course" button

**Flow:**
1. Student is redirected to results page after submission
2. Sees auto-scored L/R results immediately
3. W/S show "Pending Review" until teacher grades them
4. Once all skills graded, full results display

**SRS Reference:** Frontend 19, Backend 27
**Priority:** Must Have

---

### US-SL-22: Receive Post-Exam Routing (Pass)

**As a** self-learning student who met or exceeded my target band, **I want to** see a congratulatory message with options to register for the official IELTS exam or continue studying, **so that** I know I've reached my goal.

**Acceptance Criteria:**
- [ ] Action card: "Congratulations! You've reached your target."
- [ ] "Register for Official IELTS Exam" button -> navigates to `/student/exam-registration`
- [ ] "Continue Studying" button -> navigates to `/student/dashboard`

**Flow:**
1. Student views results showing target met
2. Action card appears at bottom
3. Student chooses next step

**SRS Reference:** Frontend 20
**Priority:** Should Have

---

### US-SL-23: Receive Post-Exam Routing (Below Target)

**As a** self-learning student who scored below my target band, **I want to** see my skill gaps and an option to start adaptive training, **so that** I can work on my weaknesses.

**Acceptance Criteria:**
- [ ] Action card: "Let's build a plan to reach your target."
- [ ] Skill gap summary shown inline
- [ ] "Start Adaptive Training" button -> navigates to `/student/course/generate?from=exam&examId={id}`

**Flow:**
1. Student views results showing target not met
2. Action card with gap summary appears
3. Student clicks "Start Adaptive Training"

**SRS Reference:** Frontend 20
**Priority:** Should Have

---

## 1E. Course Learning

### US-SL-24: View Gap Analysis

**As a** self-learning student, **I want to** see a detailed skill gap analysis from my exam or placement results, **so that** I understand which areas need the most work.

**Acceptance Criteria:**
- [ ] Gap analysis page at `/student/course/generate`
- [ ] Bar chart: skills ranked by gap size (largest first), current vs target
- [ ] Table: Skill, Current Level, Target Level, Gap, Priority (High/Medium/Low), Est. Hours
- [ ] Question-type weaknesses expandable per skill
- [ ] Topic weaknesses grouped by category
- [ ] "Generate Course" button to auto-generate a course

**Flow:**
1. Student navigates to gap analysis
2. Reviews skill gaps and weakness breakdowns
3. Clicks "Generate Course"

**SRS Reference:** Frontend 21, Backend 29
**Priority:** Must Have

---

### US-SL-25: Start Auto-Generated Course

**As a** self-learning student, **I want to** view an auto-generated course structure based on my gap analysis and start learning immediately, **so that** I don't have to wait for a teacher to build a course.

**Acceptance Criteria:**
- [ ] Read-only course preview: title, duration estimate, module list with skill assignments, hours, resource icons
- [ ] "Start Course" button begins the course
- [ ] "Customize" button (optional) allows minor adjustments (reorder modules, skip low-priority skills)
- [ ] Course is created via `POST /api/course/auto-generate`

**Flow:**
1. System generates course structure from gap analysis
2. Student reviews the proposed course
3. Clicks "Start Course"
4. Course page opens with modules available

**SRS Reference:** Frontend 22, Backend 30
**Priority:** Must Have

---

### US-SL-26: Start AI-Generated General English Course

**As a** self-learning student studying General English, **I want to** launch an AI-generated course tailored to my CEFR level and learning style, **so that** I receive personalised content without waiting for a teacher.

**Acceptance Criteria:**
- [ ] Confirmation screen shows: Current CEFR Level, Target CEFR Level (editable), Learning Style (editable), Estimated Duration
- [ ] "Start AI Course" triggers content generation via `POST /api/ai-course/english/create`
- [ ] Progress indicator during generation: "Generating your personalised course... Step 2/5: Creating grammar exercises." (1-2 min)
- [ ] Three parallel module tracks: Grammar Track, Skills Track, Vocabulary Track
- [ ] Each module: title, completion status, estimated time, "Start" / "Continue" button
- [ ] Level-up celebration modal when a level is achieved

**Flow:**
1. Student reviews profile settings
2. Clicks "Start AI Course"
3. Waits for generation (1-2 min)
4. Course appears with three parallel tracks
5. Student progresses through modules

**SRS Reference:** Frontend 28, Backend 36
**Priority:** Must Have

---

### US-SL-27: Start AI-Generated IELTS Course

**As a** self-learning student preparing for IELTS, **I want to** launch an AI-generated IELTS course that targets my weakest skills, **so that** I get focused practice aligned with real IELTS standards.

**Acceptance Criteria:**
- [ ] Profile summary: Exam Type, Current Bands per skill, Target Band (editable), Skills ranked by gap, Weak question types
- [ ] "Start AI IELTS Course" triggers per-skill content generation
- [ ] Generation progress per skill: "Listening: Generating... Creating audio scripts for Parts 1-4"
- [ ] Four parallel skill paths: Writing, Reading, Speaking, Listening
- [ ] Readiness check modal when engine determines target band likely reached
- [ ] Practice exam option for band confirmation

**Flow:**
1. Student reviews IELTS gap profile
2. Clicks "Start AI IELTS Course"
3. Waits for per-skill generation
4. Progresses through four skill paths
5. Takes practice exam when prompted

**SRS Reference:** Frontend 29, Backend 37
**Priority:** Must Have

---

### US-SL-28: Progress Through Course Modules

**As a** self-learning student, **I want to** progress through my course modules, viewing my completion status and unlocking new modules, **so that** I learn systematically.

**Acceptance Criteria:**
- [ ] Course page at `/student/course/:courseId`
- [ ] Header: title, overall progress %, estimated time remaining
- [ ] Module list with collapsible sections per skill
- [ ] Each module: status (locked/available/in-progress/completed), progress bar, resource list with type icons and completion checkmarks
- [ ] "Start" / "Continue" button per module
- [ ] Adaptive indicators (if adaptive progression): "Recommended Next" badge, "Unlocked!" animation, "Skipped" badge for mastered modules

**Flow:**
1. Student opens course page
2. Sees module list with statuses
3. Opens the next available module
4. Progresses through resources

**SRS Reference:** Frontend 24, Backend 31
**Priority:** Must Have

---

### US-SL-29: View In-Platform Resources

**As a** self-learning student, **I want to** view course resources (PDF, video, audio, exercises) directly on the platform without downloading, **so that** I can learn seamlessly.

**Acceptance Criteria:**
- [ ] PDF: embedded viewer (browser native or react-pdf)
- [ ] Video: HTML5 `<video>` player with controls and progress tracking
- [ ] Audio: HTML5 `<audio>` player with waveform
- [ ] Exercise: interactive question renderer (same components as exam)
- [ ] AI-generated content: rendered text/HTML inline
- [ ] Resource completion tracked via `POST /api/course/:courseId/progress`

**Flow:**
1. Student clicks a resource within a module
2. Resource opens in-platform
3. Student completes/views the resource
4. Completion is tracked automatically

**SRS Reference:** Frontend 24, Backend 31
**Priority:** Must Have

---

### US-SL-30: Complete Checkpoint Exercises

**As a** self-learning student, **I want to** complete checkpoint exercises within a module and see my score, **so that** I know if I've mastered the material before moving on.

**Acceptance Criteria:**
- [ ] Checkpoint exercises use the same interactive question renderer as exams
- [ ] Score shown immediately after submission
- [ ] If score below threshold: engine may insert remedial resources
- [ ] Completion criteria applied (e.g., "Score 70%+ on exercises")
- [ ] Checkpoint scored via `POST /api/course/:courseId/checkpoint`

**Flow:**
1. Student reaches a checkpoint exercise in a module
2. Answers all questions
3. Submits and sees score
4. If passed: module marked as progressed. If failed: remedial content may appear.

**SRS Reference:** Frontend 24, Backend 31
**Priority:** Must Have

---

### US-SL-31: Take Post-Course Assessment

**As a** self-learning student who completed all course modules, **I want to** take a post-course assessment and compare my results to my pre-course scores, **so that** I can see how much I've improved.

**Acceptance Criteria:**
- [ ] Completion celebration screen when all modules done
- [ ] "Take Post-Course Assessment" button assigns a practice exam (same type as diagnostic)
- [ ] After the assessment: side-by-side comparison of pre-test vs post-test scores
- [ ] Improvement visualisation (before vs after chart)

**Flow:**
1. Student completes all modules
2. Celebration screen appears
3. Clicks "Take Post-Course Assessment"
4. Takes the practice exam
5. Views improvement comparison

**SRS Reference:** Frontend 24, Backend 31
**Priority:** Should Have

---

## 1F. Score and Reporting

### US-SL-32: Download PDF Report with QR Code

**As a** self-learning student, **I want to** download a PDF report of my exam results that includes a QR code for verification, **so that** I can share my results officially.

**Acceptance Criteria:**
- [ ] "Download PDF Report" button on results page
- [ ] Loading state: "Generating your report..." spinner
- [ ] PDF includes: EnCoach logo, student info, exam info, per-skill scores, overall band, performance summary, QR code at bottom-right
- [ ] QR code encodes: student_id, exam_id, score, issue_date, verification_hash
- [ ] PDF downloads to the student's device

**Flow:**
1. Student views exam results
2. Clicks "Download PDF Report"
3. Waits for generation
4. PDF downloads

**SRS Reference:** Frontend 38, Backend 28
**Priority:** Must Have

---

# SECTION 2 -- UNIVERSITY / ENTITY STUDENT JOURNEY

The journey of a student whose account is created by their institution. Key differences from self-learner: no self-registration, no onboarding wizard, no payment step, mandatory placement test, results may require admin approval, entity branding applied.

---

## 2A. First Access

### US-ES-01: Receive Credentials and First Login

**As a** university student, **I want to** log in using the credentials provided by my institution (email + national ID as default password), **so that** I can access the platform for the first time.

**Acceptance Criteria:**
- [ ] Student receives email with: platform URL, username (institutional email), default password (national ID)
- [ ] Student logs in at `/login` with entity branding applied (logo, colours) if configured
- [ ] System detects `first_login = true`
- [ ] Student is immediately redirected to `/reset-password`
- [ ] No other page is accessible until password is reset

**Flow:**
1. Student receives credentials email from institution
2. Opens the platform URL
3. Logs in with email and default password
4. System redirects to password reset page

**SRS Reference:** Frontend 27, Backend 33
**Priority:** Must Have

---

### US-ES-02: Set New Password on First Login

**As a** university student logging in for the first time, **I want to** set a new secure password, **so that** my account is properly secured.

**Acceptance Criteria:**
- [ ] Page at `/reset-password` shows: "Welcome to [Entity Name]'s Learning Platform" with entity branding
- [ ] Fields: New Password (with strength indicator), Confirm Password
- [ ] "Set Password & Continue" button
- [ ] After reset: `first_login` set to `false`, student redirected to `/student/placement` (mandatory placement test)
- [ ] No onboarding wizard is shown to entity students

**Flow:**
1. Student enters new password
2. Confirms password
3. Clicks "Set Password & Continue"
4. Redirected to mandatory placement test

**SRS Reference:** Frontend 27, Backend 33
**Priority:** Must Have

---

## 2B. Placement Test

### US-ES-03: Take Mandatory Placement Test

**As a** university student, **I want to** take the mandatory placement test after my first login, **so that** my institution can assess my English proficiency level.

**Acceptance Criteria:**
- [ ] Placement test flow is identical to the self-learner (US-SL-07 through US-SL-11)
- [ ] Key differences:
  - The test is mandatory (cannot be skipped)
  - A note appears: "This test is mandatory. Your results will be shared with your institution."
  - No payment/access options page after results (entity controls access)
- [ ] Entity branding applied throughout the test interface

**Flow:**
1. Student is redirected to placement briefing after password reset
2. Takes the full placement test (Grammar, Vocabulary, Reading, Speaking)
3. Submits test
4. Proceeds to results

**SRS Reference:** Frontend 7-8, Backend 15-18
**Priority:** Must Have

---

### US-ES-04: View Placement Results (Entity -- Pending Approval)

**As a** university student whose institution requires manual approval, **I want to** see that my results are under review, **so that** I know my results will be released after the institution approves them.

**Acceptance Criteria:**
- [ ] If `results_release_mode = manual_approval`: simplified results page showing "Your results are being reviewed by your institution. You will be notified when they are released."
- [ ] Actual scores are hidden until admin approves
- [ ] Once approved: full results display identical to US-SL-12 but with entity's internal level name shown alongside CEFR level (if level mapping configured)

**Flow:**
1. Student completes placement test
2. Results page shows "Results Pending" message
3. Student waits for admin approval notification
4. After approval, full results become visible

**SRS Reference:** Frontend 9, Backend 17, 27
**Priority:** Must Have

---

## 2C. Exam Taking

### US-ES-05: Take an Exam Assigned by Institution

**As a** university student, **I want to** take an exam that my teacher assigned to me, **so that** my skills are formally assessed.

**Acceptance Criteria:**
- [ ] Exam session flow identical to self-learner (US-SL-15 through US-SL-20)
- [ ] Key differences:
  - Entity branding applied
  - Access window enforced (start date, end date set by teacher)
  - If access window expired: "This exam's access window has closed. Please contact your teacher."
- [ ] Exam may be from international template or custom template

**Flow:**
1. Student receives exam assignment notification
2. Opens the exam within the access window
3. Takes the exam (same flow as self-learner)
4. Submits

**SRS Reference:** Frontend 17, Backend 25
**Priority:** Must Have

---

### US-ES-06: View Exam Results (Entity -- After Approval)

**As a** university student, **I want to** view my exam results after my institution has approved them, **so that** I can see my performance and next steps.

**Acceptance Criteria:**
- [ ] If `results_release_mode = manual_approval`: results hidden until admin approves (same pattern as US-ES-04)
- [ ] If `results_release_mode = auto`: results shown immediately (same as US-SL-21)
- [ ] Results show entity's internal level name alongside CEFR (if level mapping configured)
- [ ] "Download PDF Report" button generates entity-branded PDF (entity logo in header)

**Flow:**
1. Admin approves results (or auto-release)
2. Student is notified
3. Student views full results with entity branding
4. Downloads entity-branded PDF if needed

**SRS Reference:** Frontend 19, Backend 27-28
**Priority:** Must Have

---

## 2D. Course Learning

### US-ES-07: Take a Teacher-Configured Course

**As a** university student, **I want to** take a course that my teacher configured and assigned to me, **so that** I follow a structured learning path designed by my institution.

**Acceptance Criteria:**
- [ ] Course learning flow identical to self-learner (US-SL-28 through US-SL-30)
- [ ] Key differences:
  - Course is configured by teacher (not auto-generated by student)
  - Student cannot customise the course structure
  - Progress is visible to the teacher
  - Entity branding applied
- [ ] Same in-platform resource viewers, checkpoint exercises, and progress tracking

**Flow:**
1. Teacher assigns a course to the student
2. Student opens the course page
3. Progresses through teacher-configured modules
4. Completes checkpoint exercises
5. Teacher monitors progress

**SRS Reference:** Frontend 24, Backend 31
**Priority:** Must Have

---

## 2E. Score and Reporting

### US-ES-08: Download Entity-Branded PDF Report

**As a** university student, **I want to** download a PDF report with my institution's branding, **so that** the report looks official and is recognised by my institution.

**Acceptance Criteria:**
- [ ] Same as US-SL-32 but PDF header shows entity logo instead of (or alongside) EnCoach logo
- [ ] Entity name included in student info section
- [ ] QR verification page shows entity branding

**Flow:**
1. Student views approved exam results
2. Clicks "Download PDF Report"
3. Entity-branded PDF downloads

**SRS Reference:** Frontend 38, Backend 28
**Priority:** Must Have

---

# SECTION 3 -- ADMIN / TEACHER JOURNEY

All administrative and teacher functions, each as a standalone story.

---

## 3A. Entity Student Management

### US-AD-01: Upload Student CSV File

**As an** entity admin, **I want to** upload a CSV file containing student data, **so that** I can begin the bulk account creation process.

**Acceptance Criteria:**
- [ ] Upload page at `/admin/entity/students/upload`
- [ ] Drag-and-drop or click-to-browse file zone (accepts `.csv` only)
- [ ] "Download Template" link provides sample CSV with headers: student_name, institutional_email, national_id, student_id, enrolled_programme
- [ ] "Upload & Validate" button submits the CSV for validation
- [ ] File uploaded via `POST /api/entity/students/validate-csv` (multipart/form-data)

**Flow:**
1. Admin navigates to upload page
2. Downloads template CSV
3. Fills in student data
4. Uploads the CSV file
5. System validates and shows report

**SRS Reference:** Frontend 25, Backend 32
**Priority:** Must Have

---

### US-AD-02: Review CSV Validation Report

**As an** entity admin, **I want to** review the validation report after uploading a CSV, **so that** I can identify and fix errors before creating accounts.

**Acceptance Criteria:**
- [ ] Validation table: Row #, Student Name, Email, Status (Valid/Error/Warning), Issue description
- [ ] Summary bar: "247 valid, 3 errors, 1 warning"
- [ ] "Fix & Re-upload" button allows downloading error rows for correction
- [ ] "Confirm & Create Accounts" button enabled only when zero errors (warnings allowed)

**Flow:**
1. After upload, validation report appears
2. Admin reviews each row's status
3. If errors: downloads error rows, fixes, re-uploads
4. When all valid: clicks "Confirm & Create Accounts"

**Error / Edge Cases:**
- Duplicate emails: shown as errors
- Missing required fields: shown as errors per row
- Large CSV (1000+ rows): progress indicator during validation

**SRS Reference:** Frontend 25, Backend 32
**Priority:** Must Have

---

### US-AD-03: Create Bulk Student Accounts

**As an** entity admin, **I want to** confirm and create all validated student accounts in bulk, **so that** students can access the platform.

**Acceptance Criteria:**
- [ ] On "Confirm & Create Accounts" click: `POST /api/entity/students/bulk-create`
- [ ] Accounts created: username = institutional email, default password = national ID
- [ ] All accounts tagged with the admin's `entity_id`
- [ ] CAPTCHA is NOT required for bulk accounts
- [ ] Confirmation page: "248 student accounts created successfully"
- [ ] Table of created accounts: name, email, default password indicator, status ("Pending First Login")
- [ ] Optional "Bypass Placement" flag for students with known levels

**Flow:**
1. Admin clicks "Confirm & Create Accounts"
2. System creates accounts
3. Confirmation page shows results
4. Admin proceeds to send credentials

**SRS Reference:** Frontend 25, Backend 33
**Priority:** Must Have

---

### US-AD-04: Send Credential Emails to Students

**As an** entity admin, **I want to** send login credential emails to newly created students, **so that** they can access the platform.

**Acceptance Criteria:**
- [ ] "Send Credential Emails" button on the confirmation page
- [ ] Triggers `POST /api/entity/students/send-credentials`
- [ ] Sends email to each student with: platform URL, username, default password, instructions

**Flow:**
1. After account creation, admin clicks "Send Credential Emails"
2. System sends emails to all new students
3. Admin proceeds to credential monitoring dashboard

**SRS Reference:** Frontend 25, Backend 34
**Priority:** Must Have

---

### US-AD-05: Monitor Credential Delivery Status

**As an** entity admin, **I want to** track which students have received their credentials, logged in, and started placement, **so that** I can follow up with those who haven't.

**Acceptance Criteria:**
- [ ] Dashboard at `/admin/entity/students/credentials`
- [ ] Table: Student Name, Email, Account Status (Pending First Login/Active/Password Reset Required), Email Sent (Yes/No + timestamp), First Login (Yes/No + timestamp), Placement Status (Not Started/In Progress/Completed/Bypassed)
- [ ] Per-row "Resend Email" button
- [ ] "Resend All Pending" button for bulk resend
- [ ] Bulk select with "Resend Selected" action
- [ ] Filters: Account Status, Email Sent, Placement Status, Date range

**Flow:**
1. Admin opens credential dashboard
2. Reviews delivery status per student
3. Resends to students who haven't received/opened email
4. Monitors first login and placement progress

**SRS Reference:** Frontend 26, Backend 34
**Priority:** Must Have

---

### US-AD-06: Configure Entity Level Mapping

**As an** entity admin, **I want to** map CEFR score ranges to my institution's internal level names, **so that** students and teachers see familiar level labels.

**Acceptance Criteria:**
- [ ] Config page at `/admin/entity/:entityId/level-mapping`
- [ ] Editable table: CEFR Min Score, CEFR Max Score, Internal Level Name, CEFR Equivalent
- [ ] "Add Row" to add new mappings
- [ ] "Save" persists mappings via `PUT /api/entity/:entityId/level-mapping`
- [ ] "Reset to Default" restores standard CEFR mapping
- [ ] Score ranges must not overlap (frontend validates before saving)
- [ ] Student results show both CEFR and entity's internal level name

**Flow:**
1. Admin opens level mapping config
2. Edits or adds mapping rows
3. Saves changes
4. Student results now display both levels

**SRS Reference:** Frontend 32, Backend 35
**Priority:** Should Have

---

### US-AD-07: Configure White-Label Branding

**As an** entity admin, **I want to** customise the platform's appearance with my institution's logo, colours, and subdomain, **so that** students see a branded experience.

**Acceptance Criteria:**
- [ ] Branding form at `/admin/entity/:entityId/branding`
- [ ] Fields: Logo upload (PNG/SVG/JPEG, max 2MB), Primary/Secondary/Background colour pickers, Custom Subdomain, Login Page Title, Login Page Description, Favicon
- [ ] Live preview panel on the right
- [ ] "Save Branding" persists via `PUT /api/entity/:entityId/branding`
- [ ] "Reset to Default" restores EnCoach branding
- [ ] Entity students see branding on: login page, header, dashboard, PDF reports
- [ ] Branding applied via CSS custom properties (`--primary`, `--secondary`, `--background`)
- [ ] White-labelling affects ONLY presentation, not workflow logic

**Flow:**
1. Admin opens branding settings
2. Uploads logo, picks colours, sets subdomain
3. Reviews live preview
4. Saves branding
5. All entity students see branded experience

**SRS Reference:** Frontend 33, Backend 44-45
**Priority:** Should Have

---

## 3B. Exam Configuration -- International Template (IELTS)

### US-AD-08: Select Exam Template Path

**As a** teacher, **I want to** choose between an international template and a custom exam on the template selection page, **so that** I use the right approach for my testing needs.

**Acceptance Criteria:**
- [ ] Template selection page at `/admin/exam/create`
- [ ] Section A: International templates grid (IELTS Academic, IELTS General Training, TOEFL, STEP, IC3) with "Locked" badge and tooltip
- [ ] Section B: "Create Custom Exam" card with plus icon
- [ ] International templates loaded from `GET /api/exam/templates?type=international`
- [ ] Clicking international template -> navigates to international template wizard
- [ ] Clicking "Create Custom Exam" -> navigates to custom exam builder

**Flow:**
1. Teacher opens `/admin/exam/create`
2. Reviews available templates
3. Clicks desired template or "Create Custom Exam"

**SRS Reference:** Frontend 11, Backend 19
**Priority:** Must Have

---

### US-AD-09: Initialise IELTS Exam

**As a** teacher, **I want to** initialise an IELTS exam by setting exam type, target band, difficulty, assembly mode, and score release mode, **so that** the exam is configured according to IELTS standards.

**Acceptance Criteria:**
- [ ] Wizard Phase 1 at `/admin/exam/ielts/create`
- [ ] Fields: Exam Type (Academic/General Training), Target Skills (checkboxes: L/R/W/S, pre-checked all), Exam Title (auto-suggested), Target Band (4.0-9.0 slider), Difficulty (Easy/Medium/Hard), Randomization toggle, Assembly Mode (Auto/Manual/Hybrid), Score Release Mode (Auto/Manual Approval)
- [ ] IELTS structure displayed as read-only: "Listening (4 parts, 40 Q), Reading (3 passages, 40 Q), Writing (2 tasks), Speaking (3 parts)"
- [ ] Structure CANNOT be modified (locked by international template)
- [ ] "Next" saves via `POST /api/exam/ielts/create`, returns `exam_id`

**Flow:**
1. Teacher fills in initialisation form
2. Reviews the locked IELTS structure
3. Clicks "Next"
4. System creates exam record, navigates to skill configuration

**SRS Reference:** Frontend 12, Backend 19-20
**Priority:** Must Have

---

### US-AD-10: Configure Listening Skill Structure

**As a** teacher, **I want to** review the fixed Listening structure (4 parts, 40 questions) and see available content pool counts, **so that** I know how much content is available for Listening.

**Acceptance Criteria:**
- [ ] Listening tab on the per-skill configuration page at `/admin/exam/ielts/:examId/skills`
- [ ] Read-only structure table: Part 1 (10 Q, Conversation, ~6 min), Part 2 (10 Q, Monologue, ~6 min), Part 3 (10 Q, Conversation, ~6 min), Part 4 (10 Q, Monologue, ~8 min)
- [ ] Available content pool count per part (e.g., "Available: 245 questions for Listening Part 1")
- [ ] "Configure Content" button navigates to content pool for Listening

**Flow:**
1. Teacher clicks Listening tab
2. Reviews the fixed structure (read-only)
3. Sees pool availability counts
4. Clicks "Configure Content" to browse/assign questions

**SRS Reference:** Frontend 13, Backend 21
**Priority:** Must Have

---

### US-AD-11: Configure Reading Skill Structure

**As a** teacher, **I want to** review the fixed Reading structure and see available content pool counts, **so that** I know how much content is available for Reading.

**Acceptance Criteria:**
- [ ] Reading tab on the per-skill configuration page
- [ ] Academic: Passage 1 (13-14 Q, Factual), Passage 2 (13-14 Q, Analytical), Passage 3 (13-14 Q, Argumentative)
- [ ] General Training: Section 1 (13-14 Q, Everyday), Section 2 (13-14 Q, Workplace), Section 3 (13-14 Q, General interest)
- [ ] Pool counts per passage/section
- [ ] "Configure Content" button

**Flow:**
1. Teacher clicks Reading tab
2. Reviews fixed structure
3. Clicks "Configure Content"

**SRS Reference:** Frontend 13, Backend 21
**Priority:** Must Have

---

### US-AD-12: Configure Writing Skill Structure

**As a** teacher, **I want to** review the fixed Writing structure (Task 1 and Task 2), **so that** I understand the writing assessment requirements.

**Acceptance Criteria:**
- [ ] Writing tab on the per-skill configuration page
- [ ] Task 1: Academic = describe visual data, General = write a letter (min 150 words)
- [ ] Task 2: Essay for both types (min 250 words)
- [ ] Pool counts for available writing prompts
- [ ] "Configure Content" button

**Flow:**
1. Teacher clicks Writing tab
2. Reviews fixed structure
3. Clicks "Configure Content"

**SRS Reference:** Frontend 13, Backend 21
**Priority:** Must Have

---

### US-AD-13: Configure Speaking Skill Structure

**As a** teacher, **I want to** review the fixed Speaking structure (3 parts), **so that** I understand the speaking assessment requirements.

**Acceptance Criteria:**
- [ ] Speaking tab on the per-skill configuration page
- [ ] Part 1: Familiar topics (4-5 min), Part 2: Cue card (3-4 min), Part 3: Abstract discussion (4-5 min)
- [ ] Pool counts for available speaking prompts/cue cards
- [ ] "Configure Content" button

**Flow:**
1. Teacher clicks Speaking tab
2. Reviews fixed structure
3. Clicks "Configure Content"

**SRS Reference:** Frontend 13, Backend 21
**Priority:** Must Have

---

### US-AD-14: Auto-Assemble Questions

**As a** teacher using Auto assembly mode, **I want to** have the system automatically select questions for all sections based on rules, **so that** the exam is assembled quickly without manual selection.

**Acceptance Criteria:**
- [ ] Content pool page at `/admin/exam/ielts/:examId/content`
- [ ] Left panel (content pool) is greyed out -- system selects automatically
- [ ] Right panel shows system-selected questions with "Swap" option per item
- [ ] Message: "System has selected 40 questions. Review below."
- [ ] Auto-assembly triggered via `POST /api/exam/ielts/:examId/auto-assemble`
- [ ] Teacher can swap individual items if needed

**Flow:**
1. Teacher opens content pool page in Auto mode
2. System auto-selects questions
3. Teacher reviews selections
4. Optionally swaps individual items
5. Clicks "Save & Continue"

**SRS Reference:** Frontend 14, Backend 22
**Priority:** Must Have

---

### US-AD-15: Manually Assemble Questions

**As a** teacher using Manual assembly mode, **I want to** browse the content pool and handpick every question, **so that** I have full control over exam content.

**Acceptance Criteria:**
- [ ] Left panel: full content pool browser with filters (Skill, Part, Difficulty, Topic, Status, Search)
- [ ] Content items as cards: preview text, difficulty badge, topic tags, usage count, quality rating
- [ ] "Add" button on each item
- [ ] Right panel: selected questions with drag-and-drop reordering
- [ ] Running count badge: "12/40 selected"
- [ ] Cannot proceed until all structural slots filled (e.g., 40/40 for Listening)
- [ ] Excluded from pool: items seen by assigned student, flagged items, retired items

**Flow:**
1. Teacher opens content pool in Manual mode
2. Filters and browses available questions
3. Clicks "Add" on each desired question
4. Reorders as needed in the right panel
5. Fills all slots (e.g., 40/40)
6. Clicks "Save & Continue"

**Error / Edge Cases:**
- Insufficient pool items: warning "Only 35 questions available (40 required)"

**SRS Reference:** Frontend 14, Backend 22
**Priority:** Must Have

---

### US-AD-16: Hybrid-Assemble Questions

**As a** teacher using Hybrid assembly mode, **I want to** review system-suggested questions and accept, reject, or swap them, **so that** I get the efficiency of auto-assembly with the control of manual selection.

**Acceptance Criteria:**
- [ ] System pre-populates suggestions (highlighted) via `POST /api/exam/ielts/:examId/suggest`
- [ ] "Accept All" button accepts all suggestions at once
- [ ] Per-item buttons: "Accept", "Reject", "Swap"
- [ ] Teacher can manually add replacements for rejected items
- [ ] "Save & Continue" when all slots filled

**Flow:**
1. Teacher opens content pool in Hybrid mode
2. System suggests questions
3. Teacher reviews each suggestion
4. Accepts, rejects, or swaps items
5. Clicks "Save & Continue"

**SRS Reference:** Frontend 14, Backend 22
**Priority:** Must Have

---

### US-AD-17: Validate Exam

**As a** teacher, **I want to** run validation checks on the assembled exam, **so that** I can identify and fix any issues before publishing.

**Acceptance Criteria:**
- [ ] Validation page at `/admin/exam/ielts/:examId/validate`
- [ ] Validation runs automatically on page load via `GET /api/exam/ielts/:examId/validate`
- [ ] Checklist: Question Count (pass/fail per section), Media URLs (accessible), Answer Keys (populated), No Duplicates, Rubrics (linked for W/S), Time Specification (valid)
- [ ] Red items block publishing; yellow items are warnings (can proceed with acknowledgement)
- [ ] "Preview Exam" opens read-only student-view preview

**Flow:**
1. Teacher opens validation page
2. Validation auto-runs
3. Reviews checklist results
4. Fixes any red items (returns to content pool)
5. Proceeds to publish when all checks pass

**SRS Reference:** Frontend 15, Backend 24
**Priority:** Must Have

---

### US-AD-18: Publish Exam

**As a** teacher, **I want to** publish a validated exam so that it becomes available for student assignment, **so that** students can take the exam.

**Acceptance Criteria:**
- [ ] "Publish" button enabled only when all validation checks pass
- [ ] On publish: `PUT /api/exam/ielts/:examId` with `status: "published"`
- [ ] After publishing, the exam is locked for editing
- [ ] "Duplicate" option allows creating a copy for modification

**Flow:**
1. Teacher clicks "Publish" on validation page
2. Exam status changes to "published"
3. Exam is locked for editing
4. Teacher can now assign it to students

**SRS Reference:** Frontend 15, Backend 24
**Priority:** Must Have

---

### US-AD-19: Assign Exam to Students

**As a** teacher, **I want to** assign a published exam to specific students or batches with optional access windows, **so that** students can take the exam within the specified time frame.

**Acceptance Criteria:**
- [ ] "Assign to Students" button opens a student/batch selector dialog
- [ ] Searchable student list and batch list
- [ ] Multiple students and batches can be selected
- [ ] Optional access window per assignment: start date, end date
- [ ] Assignment via `POST /api/exam/ielts/:examId/assign`

**Flow:**
1. Teacher clicks "Assign to Students"
2. Searches and selects students or batches
3. Optionally sets access window dates
4. Confirms assignment
5. Students receive notification

**SRS Reference:** Frontend 15, Backend 24
**Priority:** Must Have

---

## 3C. Exam Configuration -- Custom Template

### US-AD-20: Create Custom Exam -- Define Properties

**As a** teacher, **I want to** define the properties of a custom exam (title, subject, time, pass threshold, score release mode), **so that** I set up the exam's basic configuration.

**Acceptance Criteria:**
- [ ] Step 1 of custom exam creation at `/admin/exam/custom/create`
- [ ] Fields: Exam Title (required, max 200 chars), Subject (select from taxonomy -- English only for now), Description (optional), Total Time (minutes, min 5), Pass Threshold (% slider, optional), Score Release Mode (Auto/Manual Approval), Randomize Questions toggle
- [ ] No locked structural constraints -- teacher has full control
- [ ] "Next" proceeds to section builder

**Flow:**
1. Teacher fills in exam properties
2. Clicks "Next"

**SRS Reference:** Frontend 16, Backend 23
**Priority:** Must Have

---

### US-AD-21: Create Custom Exam -- Build Sections

**As a** teacher, **I want to** add and configure sections for my custom exam (section title, skill, question count, time limit, scoring method), **so that** I define the exam's structure.

**Acceptance Criteria:**
- [ ] Step 2 of custom exam creation
- [ ] Each section is a collapsible panel with: Section Title (required), Skill/Category (select or custom label), Question Count (min 1), Time Limit (minutes, optional), Scoring Method (Auto/Rubric/Mixed)
- [ ] "Add Section" button adds a new panel
- [ ] Sections reorderable via drag-and-drop
- [ ] Sections deletable with confirmation dialog
- [ ] "Next" proceeds to question assignment

**Flow:**
1. Teacher adds one or more sections
2. Configures each section
3. Reorders as needed
4. Clicks "Next"

**Error / Edge Cases:**
- Zero sections defined: "Next" disabled

**SRS Reference:** Frontend 16, Backend 23
**Priority:** Must Have

---

### US-AD-22: Create Custom Exam -- Assign Questions

**As a** teacher, **I want to** assign questions to each section from the content pool or by creating new questions inline, **so that** each section has the required content.

**Acceptance Criteria:**
- [ ] Step 3 of custom exam creation
- [ ] For each section: "Browse Content Pool" button opens shared pool with filters
- [ ] "Create New Question" button opens inline question form (type, stem, options, correct answer, marks, difficulty)
- [ ] Running count: "8/10 questions added"
- [ ] Teacher can add extras beyond defined count (held as alternates for randomization)
- [ ] Same content pool browser as international template (US-AD-15)

**Flow:**
1. Teacher opens question assignment for each section
2. Browses content pool or creates questions inline
3. Adds questions until count is met
4. Clicks "Next" to review

**SRS Reference:** Frontend 16, Backend 23
**Priority:** Must Have

---

### US-AD-23: Create Custom Exam -- Validate and Publish

**As a** teacher, **I want to** validate and publish my custom exam, **so that** students can take it.

**Acceptance Criteria:**
- [ ] Step 4: same validation and publish flow as international exam (US-AD-17, US-AD-18)
- [ ] Validation rules adapt to custom constraints: question count per section, rubrics for rubric-scored sections, valid time limits, answer keys for auto-scored questions
- [ ] "Publish" locks the exam; "Assign to Students" available after publish
- [ ] Custom exam uses same exam session, grading, and score release as international

**Flow:**
1. Validation auto-runs
2. Teacher fixes any issues
3. Publishes the exam
4. Assigns to students

**SRS Reference:** Frontend 16, Backend 23-24
**Priority:** Must Have

---

### US-AD-24: Save Custom Exam as Reusable Template

**As a** teacher, **I want to** save my custom exam's structure as a reusable template, **so that** I can create similar exams in the future without rebuilding the structure.

**Acceptance Criteria:**
- [ ] "Save as Template" option on the custom exam
- [ ] Creates a record in `encoach.exam.template` with `editable = true`, `type = custom`
- [ ] Template appears in "My Templates" section on the template selection page
- [ ] Template is scoped to the teacher and their entity

**Flow:**
1. Teacher clicks "Save as Template" on a custom exam
2. Enters a template name
3. Template is saved
4. Available for future use on the template selection page

**SRS Reference:** Frontend 16, Backend 23
**Priority:** Should Have

---

### US-AD-25: Create Exam from Saved Custom Template

**As a** teacher, **I want to** create a new exam from a previously saved custom template, **so that** I don't rebuild the same structure from scratch.

**Acceptance Criteria:**
- [ ] "My Templates" section on template selection page shows saved custom templates
- [ ] Clicking a template pre-populates the custom exam creation form with saved structure
- [ ] Teacher can modify any aspect before proceeding
- [ ] Templates scoped to the teacher and their entity

**Flow:**
1. Teacher opens template selection page
2. Clicks a saved custom template
3. Form opens pre-populated
4. Teacher modifies as needed
5. Proceeds through creation steps

**SRS Reference:** Frontend 11, 16; Backend 23
**Priority:** Should Have

---

## 3D. Grading

### US-AD-26: Grade a Writing Submission

**As a** teacher, **I want to** grade a student's writing submission using IELTS rubric criteria with optional AI suggestions, **so that** I can evaluate writing skills fairly and efficiently.

**Acceptance Criteria:**
- [ ] Grading queue at `/admin/exam/:examId/grading` (filtered to Writing)
- [ ] "Grade Now" shows: student's essay text, rubric criteria panel
- [ ] IELTS Writing rubric: Task Achievement, Coherence and Cohesion, Lexical Resource, Grammatical Range and Accuracy (each 0-9)
- [ ] "AI Grade Suggestion" button: populates rubric with AI-suggested scores via `POST /api/grading/ai-suggest`
- [ ] Teacher can accept or override each criterion
- [ ] "Submit Grade" saves and moves to next submission

**Flow:**
1. Teacher opens grading queue, filters to Writing
2. Clicks "Grade Now" on a pending submission
3. Reads the student's essay
4. Optionally clicks "AI Grade Suggestion"
5. Adjusts scores as needed
6. Clicks "Submit Grade"

**Error / Edge Cases:**
- AI suggestion fails: toast error, teacher grades manually

**SRS Reference:** Frontend 18, Backend 26
**Priority:** Must Have

---

### US-AD-27: Grade a Speaking Submission

**As a** teacher, **I want to** grade a student's speaking submission by listening to their audio recording and scoring rubric criteria with optional AI suggestions, **so that** I can evaluate speaking skills fairly and efficiently.

**Acceptance Criteria:**
- [ ] Grading queue filtered to Speaking
- [ ] "Grade Now" shows: audio playback controls, rubric criteria panel
- [ ] IELTS Speaking rubric: Fluency and Coherence, Lexical Resource, Grammatical Range and Accuracy, Pronunciation (each 0-9)
- [ ] "AI Grade Suggestion" button available
- [ ] Teacher can accept or override
- [ ] "Submit Grade" saves and moves to next

**Flow:**
1. Teacher opens grading queue, filters to Speaking
2. Clicks "Grade Now"
3. Listens to audio recording
4. Optionally gets AI suggestion
5. Adjusts scores
6. Submits grade

**Error / Edge Cases:**
- Audio playback issue: download link as fallback

**SRS Reference:** Frontend 18, Backend 26
**Priority:** Must Have

---

## 3E. Course Management

### US-AD-28: View Student Gap Analysis

**As a** teacher, **I want to** view a student's skill gap analysis from their exam or placement results, **so that** I can design an appropriate course for them.

**Acceptance Criteria:**
- [ ] Gap analysis page (entity teacher view) at `/student/course/generate`
- [ ] Same visualisation as US-SL-24: bar chart, table, question-type weaknesses, topic weaknesses
- [ ] View-only for entity students: "Your teacher will configure your course based on these results."
- [ ] Teacher sees all enrolled students' gap analyses

**Flow:**
1. Teacher navigates to gap analysis for a student
2. Reviews skill gaps and weakness breakdowns
3. Proceeds to configure a course

**SRS Reference:** Frontend 21, Backend 29
**Priority:** Must Have

---

### US-AD-29: Configure Course Structure

**As a** teacher, **I want to** configure a course with title, target, duration, skills, skill weightings, and progression model, **so that** the course is appropriately scoped for my students.

**Acceptance Criteria:**
- [ ] Config form at `/admin/course/configure/:courseId`
- [ ] Fields: Course Title, Exam Type (IELTS Academic/General Training/General English), Target Band/Level, Duration (weeks, 1-52), Study Hours/Week (1-40 slider), Skills (checkboxes, pre-selected from gap analysis), Skill Weightings (sliders per skill, must sum to total hours), Progression Model (Linear/Parallel/Adaptive)
- [ ] "Adaptive" requires engine to be active; if not, defaults to "Parallel" with note
- [ ] "Create Course" saves via `POST /api/course/create`, navigates to module builder

**Flow:**
1. Teacher fills in course parameters
2. Adjusts skill weightings
3. Selects progression model
4. Clicks "Create Course"

**SRS Reference:** Frontend 22, Backend 30
**Priority:** Must Have

---

### US-AD-30: Build Course Modules

**As a** teacher, **I want to** create modules within each skill section of a course, **so that** the course has structured learning content.

**Acceptance Criteria:**
- [ ] Module builder at `/admin/course/:courseId/modules`
- [ ] Collapsible panels per skill section
- [ ] Module fields: Title, Estimated Hours, Completion Criteria (complete all / score 70%+ / teacher approval), Prerequisite Module (optional)
- [ ] Modules reorderable via drag-and-drop
- [ ] "Add Module" button per skill section

**Flow:**
1. Teacher opens module builder
2. Adds modules to each skill section
3. Configures each module
4. Reorders as needed

**SRS Reference:** Frontend 23, Backend 30
**Priority:** Must Have

---

### US-AD-31: Attach Resources to Modules

**As a** teacher, **I want to** attach learning resources (PDF, video, audio, exercises) to a course module, **so that** students have content to study.

**Acceptance Criteria:**
- [ ] Resource attachment panel within each module
- [ ] "Browse Resources" button opens search/browse modal: `GET /api/resources?skill={skill}&difficulty={level}&type={type}`
- [ ] Supports: PDF, Video, Audio, Exercise, AI-generated content
- [ ] Resources selected from the shared content database

**Flow:**
1. Teacher clicks "Browse Resources" within a module
2. Searches and filters available resources
3. Selects resources to attach
4. Resources appear in the module's resource list

**SRS Reference:** Frontend 23, Backend 30
**Priority:** Must Have

---

### US-AD-32: Generate AI Content for a Module

**As a** teacher, **I want to** request AI-generated learning content for a specific module, **so that** I can fill content gaps without creating everything manually.

**Acceptance Criteria:**
- [ ] "Generate AI Content" button within each module
- [ ] Brief form: topic, difficulty, content type (reading passage, grammar exercise, vocabulary set, etc.)
- [ ] Calls `POST /api/ai/generate-resource`
- [ ] Generated content appears in the module after quality gate approval

**Flow:**
1. Teacher clicks "Generate AI Content" in a module
2. Fills in topic, difficulty, type
3. System generates content
4. Content goes through quality gate
5. Approved content added to module

**SRS Reference:** Frontend 23, Backend 36
**Priority:** Should Have

---

### US-AD-33: Publish and Assign Course

**As a** teacher, **I want to** publish a course and assign it to students, **so that** students can begin learning.

**Acceptance Criteria:**
- [ ] "Publish Course" button on the module builder page
- [ ] Calls `PUT /api/course/:courseId` with `status: "published"`
- [ ] Course assigned to the target student(s)
- [ ] Students receive notification

**Flow:**
1. Teacher finishes building modules
2. Clicks "Publish Course"
3. Course is published and assigned
4. Students can now access it

**SRS Reference:** Frontend 23, Backend 30
**Priority:** Must Have

---

### US-AD-34: Monitor Student Course Progress

**As a** teacher, **I want to** view a dashboard of enrolled students' progress, time spent, and predicted improvement, **so that** I can identify struggling students and intervene.

**Acceptance Criteria:**
- [ ] Progress dashboard at `/teacher/course/:courseId/progress`
- [ ] Table: Student Name, Overall Progress (%), Current Module, Time Spent (hours), Predicted Band Improvement, Last Activity, Alert ("No progress for 3+ days")
- [ ] Clicking student name opens detailed profile
- [ ] Alert icon for students with no progress 3+ days

**Flow:**
1. Teacher opens course progress dashboard
2. Reviews student progress
3. Identifies students with alerts
4. Clicks student name for detailed analysis

**SRS Reference:** Frontend 24, Backend 31
**Priority:** Should Have

---

## 3F. AI Content Quality

### US-AD-35: Review AI-Generated English Content (Quality Gate)

**As a** teacher or admin, **I want to** review AI-generated General English content through automated quality checks, **so that** I can ensure it meets pedagogical standards.

**Acceptance Criteria:**
- [ ] Quality gate page shows: Readability Score (Flesch-Kincaid vs target range), CEFR Calibration, Grammar Accuracy, Length Compliance
- [ ] Each check: Pass/Fail with specific details
- [ ] "Approve" marks content as approved
- [ ] "Reject & Regenerate" sends back to AI with error notes (max 3 attempts)
- [ ] "Edit" opens inline editor for manual correction

**Flow:**
1. Admin opens quality gate for generated content
2. Reviews automated check results
3. Approves, rejects, or edits

**SRS Reference:** Frontend 28, Backend 38
**Priority:** Must Have

---

### US-AD-36: Review AI IELTS Content -- Automated Standards Check

**As an** admin, **I want to** validate AI-generated IELTS content against automated IELTS format standards, **so that** content meets official IELTS structural requirements.

**Acceptance Criteria:**
- [ ] Layer 1 validation page
- [ ] Checks: Format Compliance (word counts, part structure, question types), CEFR Band Calibration (readability mapped to target band), Answer Key Completeness (correct answers populated, rubrics linked)
- [ ] Each check: Pass/Fail with specific issue details (e.g., "Reading Passage 2: word count 890 -- exceeds IELTS maximum of 850 words")
- [ ] Failed checks must be resolved before proceeding to examiner review

**Flow:**
1. Admin opens IELTS validation page
2. Reviews Layer 1 automated checks
3. Identifies and resolves any failures
4. Content proceeds to Layer 2 (examiner review)

**SRS Reference:** Frontend 29, Backend 39
**Priority:** Should Have

---

### US-AD-37: Review AI IELTS Content -- Examiner Review

**As an** admin, **I want to** assign IELTS examiner reviewers to AI-generated content and manage their approval, **so that** content is verified by qualified humans before students see it.

**Acceptance Criteria:**
- [ ] Layer 2 review queue: table of content items pending review
- [ ] Columns: Skill, Content Type, Target Band, Examiner (assigned or "Unassigned"), Status (Pending/Approved/Rejected)
- [ ] Review interface: full content preview, examiner checklist (accuracy, difficulty, IELTS alignment, cultural sensitivity)
- [ ] "Approve" marks as `ielts_certified = true`
- [ ] "Reject with Notes" returns to AI for regeneration
- [ ] AI-generated content requires mandatory review; entity-uploaded content is "Spot-check only"

**Flow:**
1. Admin assigns examiners to content items
2. Examiner reviews content, fills checklist
3. Approves or rejects
4. Approved content available to students

**SRS Reference:** Frontend 29, Backend 39
**Priority:** Should Have

---

## 3G. Score Release

### US-AD-38: Approve Exam Results

**As an** entity admin, **I want to** approve exam results so they become visible to the student, **so that** my institution controls when scores are released.

**Acceptance Criteria:**
- [ ] Approval queue at `/admin/scores/pending`
- [ ] Only exams with `results_release_mode = manual_approval` appear
- [ ] Table: Student Name, Exam Title, Type (Official/Practice), Submitted At, Overall Score, Status, Action
- [ ] "Approve" calls `POST /api/scores/:attemptId/release`; student is notified
- [ ] Bulk action: "Approve All Selected"
- [ ] Practice exams (auto release) never appear in this queue

**Flow:**
1. Admin opens approval queue
2. Reviews pending results
3. Clicks "Approve" for each (or bulk approve)
4. Students are notified and can see results

**SRS Reference:** Frontend 37, Backend 27
**Priority:** Must Have

---

### US-AD-39: Reject Exam Results with Reason

**As an** entity admin, **I want to** reject exam results with a specific reason, **so that** the student is informed about why their results need further review.

**Acceptance Criteria:**
- [ ] "Reject" button opens a reason dialog
- [ ] Admin enters reason text
- [ ] Calls `POST /api/scores/:attemptId/reject` with reason
- [ ] Student sees: "Your results require further review. Reason: [reason]."

**Flow:**
1. Admin clicks "Reject" on a pending result
2. Enters reason in dialog
3. Submits rejection
4. Student sees rejection message with reason

**SRS Reference:** Frontend 37, Backend 27
**Priority:** Must Have

---

## 3H. Adaptive Engine

### US-AD-40: View Adaptive Engine Dashboard

**As an** admin, **I want to** see an overview of the adaptive learning engine's activity, **so that** I can monitor system-wide performance.

**Acceptance Criteria:**
- [ ] Dashboard at `/admin/adaptive/dashboard`
- [ ] Metrics: Active Students count, Engine Phase (1-4), Decisions Today, Average Improvement, Alerts count
- [ ] Student table: Name, Subject (English/IELTS), Current Level, Target Level, Days Active, Last Decision, Progress Trend (sparkline), Alert

**Flow:**
1. Admin opens adaptive dashboard
2. Reviews system-wide metrics
3. Identifies students needing attention

**SRS Reference:** Frontend 30, Backend 40-43
**Priority:** Should Have

---

### US-AD-41: Configure Adaptive Engine Thresholds

**As a** teacher, **I want to** set thresholds for the adaptive engine, **so that** I control how it adapts content for my students.

**Acceptance Criteria:**
- [ ] Settings at `/teacher/adaptive/settings`
- [ ] Thresholds: Difficulty Step-Up (default 85%), Difficulty Step-Down (default 50%), Micro-Lesson Trigger (default 2), Module Skip (default 95%), No-Progress Alert Days (default 3), Max Retries (default 3)
- [ ] "Save" via `PUT /api/adaptive/settings`
- [ ] No-progress alerts show as visual badges on teacher sidebar

**Flow:**
1. Teacher opens adaptive settings
2. Adjusts thresholds
3. Saves

**SRS Reference:** Frontend 30, Backend 40
**Priority:** Should Have

---

### US-AD-42: View Student Adaptive Signals and Decisions

**As a** teacher, **I want to** view a timeline of all engine signals and decisions for a specific student, **so that** I understand why the engine made specific content decisions.

**Acceptance Criteria:**
- [ ] Detail page at `/admin/adaptive/student/:studentId`
- [ ] Signal timeline: Time, Signal (quiz score, time on task, retry count, module completion), Value, Decision Made
- [ ] For IRT phases (Phase 2+): ability estimate (theta), SEM, ability trajectory chart

**Flow:**
1. Teacher clicks student name from adaptive dashboard
2. Views signal timeline
3. Understands engine decisions
4. Optionally adjusts thresholds

**SRS Reference:** Frontend 31, Backend 40-43
**Priority:** Could Have

---

## 3I. Public Verification

### US-PV-01: Verify a Score via QR Code

**As a** public verifier (employer, university), **I want to** scan a QR code from a student's PDF report and see verified score information, **so that** I can confirm the authenticity of the student's results.

**Acceptance Criteria:**
- [ ] Public page at `/verify/:verificationHash` -- NO authentication required
- [ ] Valid hash: displays student name, exam title, exam date, overall score, per-skill scores, "Verified" badge (green checkmark)
- [ ] Invalid/tampered hash: "This score could not be verified. The verification link may be invalid or expired." (red badge)
- [ ] Page shows EnCoach logo (or entity logo if white-labelled)

**Flow:**
1. Verifier scans QR code on student's PDF
2. Browser opens verification page
3. Sees verified score details (or error if invalid)

**SRS Reference:** Frontend 39, Backend 28
**Priority:** Must Have

---

# APPENDIX A -- Story Map Summary

| ID | Title | Actor | Section | Priority |
|----|-------|-------|---------|----------|
| US-SL-01 | Register a New Account | Self-Learner | 1A | Must Have |
| US-SL-02 | Verify Email Address | Self-Learner | 1A | Must Have |
| US-SL-03 | Select Learning Goal | Self-Learner | 1B | Must Have |
| US-SL-04 | Set Target Level and Timeline | Self-Learner | 1B | Must Have |
| US-SL-05 | Set Study Preferences | Self-Learner | 1B | Must Have |
| US-SL-06 | Choose Placement Test Decision | Self-Learner | 1B | Must Have |
| US-SL-07 | View Placement Test Briefing | Self-Learner | 1C | Must Have |
| US-SL-08 | Placement Test -- Grammar | Self-Learner | 1C | Must Have |
| US-SL-09 | Placement Test -- Vocabulary | Self-Learner | 1C | Must Have |
| US-SL-10 | Placement Test -- Reading | Self-Learner | 1C | Must Have |
| US-SL-11 | Placement Test -- Speaking | Self-Learner | 1C | Must Have |
| US-SL-12 | View Placement Results | Self-Learner | 1C | Must Have |
| US-SL-13 | View Learning Path Preview | Self-Learner | 1C | Must Have |
| US-SL-14 | Choose Payment Option | Self-Learner | 1C | Should Have |
| US-SL-15 | Start Exam Session | Self-Learner | 1D | Must Have |
| US-SL-16 | Answer Listening Questions | Self-Learner | 1D | Must Have |
| US-SL-17 | Answer Reading Questions | Self-Learner | 1D | Must Have |
| US-SL-18 | Complete Writing Tasks | Self-Learner | 1D | Must Have |
| US-SL-19 | Record Speaking Responses | Self-Learner | 1D | Must Have |
| US-SL-20 | Review and Submit Exam | Self-Learner | 1D | Must Have |
| US-SL-21 | View Exam Results (Auto) | Self-Learner | 1D | Must Have |
| US-SL-22 | Post-Exam Routing (Pass) | Self-Learner | 1D | Should Have |
| US-SL-23 | Post-Exam Routing (Below Target) | Self-Learner | 1D | Should Have |
| US-SL-24 | View Gap Analysis | Self-Learner | 1E | Must Have |
| US-SL-25 | Start Auto-Generated Course | Self-Learner | 1E | Must Have |
| US-SL-26 | Start AI English Course | Self-Learner | 1E | Must Have |
| US-SL-27 | Start AI IELTS Course | Self-Learner | 1E | Must Have |
| US-SL-28 | Progress Through Modules | Self-Learner | 1E | Must Have |
| US-SL-29 | View In-Platform Resources | Self-Learner | 1E | Must Have |
| US-SL-30 | Complete Checkpoint Exercises | Self-Learner | 1E | Must Have |
| US-SL-31 | Take Post-Course Assessment | Self-Learner | 1E | Should Have |
| US-SL-32 | Download PDF Report | Self-Learner | 1F | Must Have |
| US-ES-01 | First Login | Entity Student | 2A | Must Have |
| US-ES-02 | Set New Password | Entity Student | 2A | Must Have |
| US-ES-03 | Take Mandatory Placement Test | Entity Student | 2B | Must Have |
| US-ES-04 | View Results (Pending Approval) | Entity Student | 2B | Must Have |
| US-ES-05 | Take Assigned Exam | Entity Student | 2C | Must Have |
| US-ES-06 | View Results (After Approval) | Entity Student | 2C | Must Have |
| US-ES-07 | Take Teacher-Configured Course | Entity Student | 2D | Must Have |
| US-ES-08 | Download Entity-Branded PDF | Entity Student | 2E | Must Have |
| US-AD-01 | Upload Student CSV | Admin | 3A | Must Have |
| US-AD-02 | Review CSV Validation | Admin | 3A | Must Have |
| US-AD-03 | Create Bulk Accounts | Admin | 3A | Must Have |
| US-AD-04 | Send Credential Emails | Admin | 3A | Must Have |
| US-AD-05 | Monitor Credential Delivery | Admin | 3A | Must Have |
| US-AD-06 | Configure Level Mapping | Admin | 3A | Should Have |
| US-AD-07 | Configure White-Label Branding | Admin | 3A | Should Have |
| US-AD-08 | Select Template Path | Teacher | 3B | Must Have |
| US-AD-09 | Initialise IELTS Exam | Teacher | 3B | Must Have |
| US-AD-10 | Configure Listening Structure | Teacher | 3B | Must Have |
| US-AD-11 | Configure Reading Structure | Teacher | 3B | Must Have |
| US-AD-12 | Configure Writing Structure | Teacher | 3B | Must Have |
| US-AD-13 | Configure Speaking Structure | Teacher | 3B | Must Have |
| US-AD-14 | Auto-Assemble Questions | Teacher | 3B | Must Have |
| US-AD-15 | Manually Assemble Questions | Teacher | 3B | Must Have |
| US-AD-16 | Hybrid-Assemble Questions | Teacher | 3B | Must Have |
| US-AD-17 | Validate Exam | Teacher | 3B | Must Have |
| US-AD-18 | Publish Exam | Teacher | 3B | Must Have |
| US-AD-19 | Assign Exam to Students | Teacher | 3B | Must Have |
| US-AD-20 | Custom Exam -- Properties | Teacher | 3C | Must Have |
| US-AD-21 | Custom Exam -- Sections | Teacher | 3C | Must Have |
| US-AD-22 | Custom Exam -- Questions | Teacher | 3C | Must Have |
| US-AD-23 | Custom Exam -- Validate/Publish | Teacher | 3C | Must Have |
| US-AD-24 | Save as Template | Teacher | 3C | Should Have |
| US-AD-25 | Create from Template | Teacher | 3C | Should Have |
| US-AD-26 | Grade Writing Submission | Teacher | 3D | Must Have |
| US-AD-27 | Grade Speaking Submission | Teacher | 3D | Must Have |
| US-AD-28 | View Student Gap Analysis | Teacher | 3E | Must Have |
| US-AD-29 | Configure Course Structure | Teacher | 3E | Must Have |
| US-AD-30 | Build Course Modules | Teacher | 3E | Must Have |
| US-AD-31 | Attach Resources to Modules | Teacher | 3E | Must Have |
| US-AD-32 | Generate AI Content | Teacher | 3E | Should Have |
| US-AD-33 | Publish and Assign Course | Teacher | 3E | Must Have |
| US-AD-34 | Monitor Student Progress | Teacher | 3E | Should Have |
| US-AD-35 | Quality Gate -- English | Admin | 3F | Must Have |
| US-AD-36 | IELTS Standards Check | Admin | 3F | Should Have |
| US-AD-37 | IELTS Examiner Review | Admin | 3F | Should Have |
| US-AD-38 | Approve Exam Results | Admin | 3G | Must Have |
| US-AD-39 | Reject Exam Results | Admin | 3G | Must Have |
| US-AD-40 | Adaptive Dashboard | Admin | 3H | Should Have |
| US-AD-41 | Adaptive Thresholds | Teacher | 3H | Should Have |
| US-AD-42 | Student Signals/Decisions | Teacher | 3H | Could Have |
| US-PV-01 | Verify Score via QR | Public | 3I | Must Have |

---

## Summary

| Metric | Count |
|--------|-------|
| **Total User Stories** | 83 |
| **Section 1 (Self-Learner)** | 32 |
| **Section 2 (Entity Student)** | 8 |
| **Section 3 (Admin/Teacher)** | 42 |
| **Section 3 (Public Verifier)** | 1 |
| **Must Have** | 62 |
| **Should Have** | 18 |
| **Could Have** | 3 |
| **Scope** | English Only (General English + IELTS) |

---

## End of Document

**Document Version:** 2.0
**Total User Stories:** 83
**Scope:** English Only (General English + IELTS). Math/IT deferred to future phase.
**Structure:** 3 actor journeys -- Self-Learner, Entity Student, Admin/Teacher -- each with atomic, per-function stories.
**Companion SRS Versions:** Frontend v1.1, Backend v1.1