devops/encoach_backend_new_v2
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity
Files
096b042daf36041aa89cc9164c3b32147e33d247
encoach_backend_new_v2/docs/ENCOACH_USER_STORIES.md
Yamen Ahmad f1c4953a63 feat(v3): restructure project + add complete frontend 
- Restructure: move backend from new_project/ to backend/
- Add full React/TypeScript frontend (37 pages, 17 services, 16 type defs, 11 query hooks)
- Add docs/ with SRS specs, user stories, and workflow documentation
- Update .gitignore for new directory layout

Workflows implemented:
  WF1 User Signup, WF2 Placement Test, WF3 Exam Configuration,
  WF4 General English Exam, WF5 Course Generation,
  WF6 Entity Student Onboarding, AI Course Generation,
  Adaptive Learning Engine UI, White-Label Branding, Score Release

Made-with: Cursor
2026-04-10 17:26:42 +04:00

82 KiB
Raw Blame History

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

Reference in New Issue View Git Blame Copy Permalink