encoach_frontend_new_v2/new_project/ENCOACH_WORKFLOWS_FRONTEND_SRS.md

EnCoach Platform -- Frontend Software Requirements Specification

Document Version: 1.1 Date: April 2026 Status: Active -- Ready for Development Source Document: encoach_workflows_v3.pdf (v3.0, April 2026) Audience: Odoo Developer (full-stack, using Cursor IDE) Scope: All new frontend pages, components, and UI flows required to implement the 6 platform workflows, exam template paths (international + custom), adaptive learning engine, Math/IT support, and white-labelling.

---

Implementation Context

Artifact	Location
Frontend Repository	https://git.albousalh.com/devops/encoach_frontend_new_v2.git (branch: main)
Backend Repository	https://git.albousalh.com/devops/encoach_backend_new_v2.git (branch: main)
Staging Frontend	http://5.189.151.117:3000
Staging Backend (Odoo 19)	http://5.189.151.117:8069
Frontend Stack	React 18, TypeScript, Vite 5, shadcn/ui, TanStack Query v5, React Router v6
Backend Stack	Odoo 19, Python 3.11, PostgreSQL 16, Docker Compose

---

Table of Contents

Part I -- Context and Baseline

1. Introduction
2. Existing System Summary
3. Architecture and Conventions

Part II -- Workflow 1: User Signup (Individual) 4. Registration Page 5. Email Verification Page 6. Onboarding Wizard

Part III -- Workflow 2: Placement Test 7. Placement Test Briefing 8. CAT Test Interface 9. Placement Results and Learning Path Preview 10. Payment and Access Options

Part IV -- Workflow 3: Exam Configuration (International + Custom) 11. Exam Template Paths 12. International Template -- IELTS Exam Initialization 13. Per-Skill Configuration Panels 14. Content Pool and Question Assembly 15. Exam Assembly and Validation 16. Custom Template -- Exam Creation

Part V -- Workflow 4: General English Exam 17. Exam Session Interface 18. Grading and Score Release 19. Results Display and Reporting 20. Result Routing

Part VI -- Workflow 5: Course Generation 21. Gap Analysis Dashboard 22. Course Structure Configuration 23. Module Builder 24. Course Delivery and Progress

Part VII -- Workflow 6: Entity Student Onboarding 25. Admin Bulk Upload Interface 26. Credential Delivery Dashboard 27. Entity Student First Login

Part VIII -- AI Course Generation 28. General English AI Course Generation 29. AI IELTS Course Generation

Part IX -- Adaptive Learning Engine UI 30. Adaptive Engine Dashboard 31. Engine Signals and Decision Visualization

Part X -- Entity Management and White-Labelling 32. Entity Level Mapping Configuration 33. White-Label Branding Settings

Part XI -- Math and IT Subject Support 34. Math Content Rendering 35. IT Content Rendering 36. Subject-Agnostic Placement and Courses

Part XII -- Score Release and Reporting 37. Admin Score Approval Queue 38. PDF Report with QR Code 39. Public Score Verification Page

Part XIII -- Technical Specifications 40. New Pages Inventory 41. New Services Inventory 42. New Types Inventory 43. API Contracts

---

Part I -- Context and Baseline

1. Introduction

1.1 Purpose

This document specifies every frontend page, component, and user interaction required to implement the EnCoach platform workflows as defined in encoach_workflows_v3.pdf (v3.0). It is the single source of truth for frontend development of the workflow features.

1.2 Scope

The document covers 6 workflows, the adaptive learning engine (4 phases), Math/IT subject support, white-labelling, and score release/reporting. Each section describes:

• What the user sees -- page layout, components, form fields
• What the user does -- interactions, validations, navigation flow
• What the frontend calls -- API endpoints, request/response shapes
• Error and edge cases -- validation messages, loading states, empty states

1.3 Audience

This document is written for a full-stack Odoo developer who will implement both the frontend React code and the backend Odoo modules. The developer uses Cursor IDE and has access to both the frontend and backend repositories.

1.4 Design Principles (from Workflow Document)

#	Principle	Impact on Frontend
1	Exam type is always the root parameter	Every exam/course flow starts with an exam type selector (Academic vs General Training)
2	Learning path shown before payment	Student sees their personalised course plan BEFORE any payment prompt
3	Teacher as supervisor, not builder	In adaptive mode, teacher UI shows oversight controls (thresholds, alerts), not manual sequencing
4	All results stored on all paths	Every exam attempt shows in student history regardless of pass/fail
5	Shared content database	Content pool browser shows all content once -- never duplicated across exam and course views
6	White-labelling support	All student-facing pages apply entity branding (logo, colours) when student is linked to an entity

1.5 Workflow Coverage

#	Workflow	Status	Sections
1	User Signup (Individual)	To Build	4--6
2	Placement Test	To Build	7--10
3	IELTS / English Exam Configuration	To Build	11--14
4	General English Exam Generation	To Build	15--18
5	Course Generation	To Build	19--22
6	Entity Student Onboarding	To Build	23--25
--	AI Course Generation (General English + IELTS)	To Build	26--27
--	Adaptive Learning Engine UI	To Build	28--29
--	Entity / White-Label Management	To Build	30--31
--	Math and IT Subject Support	To Build	32--34
--	Score Release and Reporting	To Build	35--37

---

2. Existing System Summary

The platform already has a working frontend with the following inventory. New workflow pages will be built alongside and integrated with this existing codebase.

2.1 Current Inventory

Category	Count	Details
Page Components	93	28 root, 33 admin, 19 student, 14 teacher
API Service Modules	37	src/services/*.service.ts
TypeScript Type Files	29	src/types/*.ts
TanStack Query Hooks	21	src/hooks/queries/*.ts

2.2 Existing Page Structure

• Public: /login, /register, /forgot-password, /apply, /faq, /exam/...
• Student (/student/*): dashboard, courses, assignments, adaptive flow, courseware, discussions
• Teacher (/teacher/*): courses, assignments, attendance, chapters, AI workbench
• Admin (/admin/*): LMS dashboard, courses, students, platform admin, users, exams, taxonomy

2.3 Key Existing Components

• ProtectedRoute -- role-based route gating (student, teacher, admin, corporate, mastercorporate, agent, developer)
• StudentLayout, TeacherLayout, AdminLmsLayout -- role-specific navigation shells
• AuthContext -- JWT authentication context
• api-client.ts -- centralised Axios instance with /api proxy to Odoo backend
• query-client.ts -- TanStack Query client configuration

2.4 Tech Stack

Technology	Version	Purpose
React	18	UI framework
TypeScript	5.8	Type safety
Vite	5	Build tool (SWC plugin)
React Router	6	Client-side routing
TanStack Query	5	Server state management
shadcn/ui + Radix	Latest	Component library
Tailwind CSS	3	Styling
react-hook-form + Zod	Latest	Form management and validation
recharts	Latest	Charts and data visualization
lucide-react	Latest	Icons

---

3. Architecture and Conventions

3.1 File Organization

All new files must follow the existing project structure:

src/
  pages/
    admin/           # Admin-facing pages (exam config, bulk upload, score approval)
    student/         # Student-facing pages (exam session, placement, course delivery)
    teacher/         # Teacher-facing pages (content review, grading queue)
    PublicPage.tsx    # Public pages (score verification, signup)
  services/
    workflow-name.service.ts   # API service module
  types/
    workflow-name.ts           # TypeScript interfaces
  hooks/
    queries/
      useWorkflowName.ts      # TanStack Query hooks
  components/
    ui/              # Reusable shadcn primitives
    workflow-name/   # Workflow-specific components

3.2 API Communication Pattern

Every API call follows the existing pattern:

// src/services/example.service.ts
import apiClient from "@/lib/api-client";

export const exampleService = {
  getItems: () => apiClient.get("/api/example/items"),
  createItem: (data: CreateItemRequest) => apiClient.post("/api/example/items", data),
};

All endpoints are proxied through Vite dev server: /api maps to http://127.0.0.1:8069.

3.3 State Management Pattern

// src/hooks/queries/useExample.ts
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import { exampleService } from "@/services/example.service";

export const useExampleItems = () =>
  useQuery({ queryKey: ["example", "items"], queryFn: exampleService.getItems });

export const useCreateExample = () => {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: exampleService.createItem,
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["example"] }),
  });
};

3.4 Form Pattern

All forms use react-hook-form with Zod validation schemas:

const schema = z.object({ name: z.string().min(1), email: z.string().email() });
type FormData = z.infer<typeof schema>;

const form = useForm<FormData>({ resolver: zodResolver(schema) });

3.5 Routing Convention

New routes are added to src/App.tsx within the appropriate ProtectedRoute wrapper:

<Route element={<ProtectedRoute allowedRoles={["student"]} />}>
  <Route element={<StudentLayout />}>
    <Route path="/student/placement" element={<PlacementTest />} />
  </Route>
</Route>

---

Part II -- Workflow 1: User Signup (Individual)

4. Registration Page

Route: /register Access: Public (unauthenticated) Replaces/Enhances: Existing /register page

4.1 Page Layout

The registration page contains a single centered card with the following fields:

Field	Type	Validation	Notes
Full Name	Text input	Required, min 2 characters
Email	Email input	Required, valid email format	Checked for uniqueness on blur
Password	Password input	Required, min 8 characters	Strength indicator bar (weak/medium/strong)
Confirm Password	Password input	Must match password
Role	Radio group	Required, one of: academic_student, self_learner, teacher	Labels: "Academic Student", "Self-Learner", "Teacher"
CAPTCHA	CAPTCHA widget	Required	Integration with reCAPTCHA v2 or hCaptcha. Only shown for individual self-registration; entity bulk-upload accounts bypass this.
Submit	Button	All fields valid + CAPTCHA verified	Text: "Create Account"

4.2 Functional Requirements

ID	Requirement
REG-01	Password strength indicator updates in real time as user types. Strength levels: Weak (red, < 8 chars or no variety), Medium (yellow, 8+ chars with 2 of: uppercase, lowercase, number, symbol), Strong (green, 8+ chars with 3+ of: uppercase, lowercase, number, symbol).
REG-02	Email uniqueness is checked on blur via POST /api/auth/check-email. If email exists, show inline error: "An account with this email already exists."
REG-03	CAPTCHA token is included in the registration request body. Backend verifies the token before creating the account.
REG-04	On successful submission, the backend returns a 201 status. Frontend navigates to /verify-email?email={email}.
REG-05	On validation error (422), show field-level error messages returned by the backend.
REG-06	A "Already have an account? Sign in" link navigates to /login.

4.3 API Contract

Request: POST /api/auth/register

{
  "name": "string",
  "email": "string",
  "password": "string",
  "role": "academic_student | self_learner | teacher",
  "captcha_token": "string"
}

Response (201):

{
  "success": true,
  "message": "Account created. Please verify your email.",
  "user_id": 42
}

---

5. Email Verification Page

Route: /verify-email Access: Public (unauthenticated) Query Params: ?email={email}

5.1 Page Layout

Centered card with:

• Instruction text: "We've sent a 6-digit verification code to {email}"
• 6-digit OTP input (using input-otp component already in the project)
• "Verify" button
• "Resend code" link with countdown timer (disabled for 60 seconds after each send)
• Attempt counter text: "Resend attempts: {count}/3"

5.2 Functional Requirements

ID	Requirement
VERIFY-01	OTP input auto-focuses on the first digit. Each digit field advances focus to the next on input.
VERIFY-02	When all 6 digits are entered, the "Verify" button becomes enabled. Optionally, auto-submit on 6th digit.
VERIFY-03	On success (200), navigate to /onboarding (the onboarding wizard).
VERIFY-04	On invalid OTP (400), show error: "Invalid verification code. Please try again." Clear the input.
VERIFY-05	On expired OTP (410), show error: "This code has expired. Please request a new one."
VERIFY-06	"Resend code" calls POST /api/auth/resend-otp. Maximum 3 resend attempts. After 3 attempts, show: "Maximum resend attempts reached. Please contact support."
VERIFY-07	OTP expires after 15 minutes. Timer is shown below the input: "Code expires in MM:SS".

5.3 API Contract

Verify: POST /api/auth/verify-email

{ "email": "string", "otp": "string" }

Resend: POST /api/auth/resend-otp

{ "email": "string" }

---

6. Onboarding Wizard

Route: /onboarding Access: Authenticated, account status = unactivated Guard: If account is already activated, redirect to role-appropriate dashboard.

6.1 Wizard Structure

A multi-step wizard with 4 steps, a progress bar at the top showing the current step (1/4, 2/4, 3/4, 4/4), and Back/Next buttons at the bottom.

Step 1 -- Learning Goal

Field	Type	Validation	Notes
Goal	Radio card group	Required, select one	Options are dynamic, loaded from GET /api/onboarding/goals. Each option has an icon, title, and description. Examples: General English, IELTS Academic, IELTS General Training, TOEFL, STEP, Mathematics, IT, Other Certification.

Step 2 -- Target and Timeline

Field	Type	Validation	Notes
Target Level/Band	Slider or select	Required	For IELTS: band score slider 4.0--9.0 in 0.5 steps. For General English: CEFR level select (A1--C2). For Math/IT: proficiency level select (Beginner/Intermediate/Advanced).
Exam Date	Date picker	Optional	"I have an upcoming exam on..." If set, system calculates study timeline.
No Exam Date	Checkbox	--	"I don't have a specific exam date" -- hides date picker.

Step 3 -- Study Preferences

Field	Type	Validation	Notes
Hours per Week	Slider	Required, 1--40	Default: 10. Shows estimated completion time based on gap.
Study Mode	Radio group	Required	Options: "Self-study", "With a teacher".
Learning Style	Checkbox group (multi-select)	Required, at least one	Options: Visual, Audio, Reading, Mixed. Icons for each.

Step 4 -- Placement Test

Content	Description
Heading	"Ready to find your level?"
Description	"Take a short placement test (~20-30 minutes) so we can create a personalised learning plan for you."
Primary action	"Take Placement Test Now" -- navigates to /student/placement
Secondary action	"Skip for Now" -- displays a warning: "Without a placement test, we'll start you at B1 (intermediate) level. You can take the test anytime from your dashboard."

6.2 Functional Requirements

ID	Requirement
WIZ-01	Wizard state is preserved in local component state. Data is NOT submitted until the user completes all 4 steps.
WIZ-02	"Back" button on Step 1 is hidden. "Back" on Steps 2--4 returns to the previous step without losing data.
WIZ-03	On Step 4 completion (either "Take Test" or "Skip"), the wizard data is submitted via POST /api/onboarding/complete.
WIZ-04	On success, account status changes to activated. If "Take Test" was chosen, navigate to /student/placement. If "Skip", navigate to /student/dashboard.
WIZ-05	The goals list in Step 1 is fetched from the backend and is dynamic. If the platform adds a new exam template, it appears automatically.
WIZ-06	If the user closes the browser mid-wizard and logs in again, they are redirected back to /onboarding (because account status is still unactivated).

6.3 API Contract

Goals list: GET /api/onboarding/goals

{
  "goals": [
    { "id": "ielts_academic", "title": "IELTS Academic", "description": "...", "icon": "graduation-cap" },
    { "id": "general_english", "title": "General English", "description": "...", "icon": "book-open" },
    { "id": "mathematics", "title": "Mathematics", "description": "...", "icon": "calculator" }
  ]
}

Complete wizard: POST /api/onboarding/complete

{
  "goal": "ielts_academic",
  "target_band": 7.0,
  "exam_date": "2026-09-15",
  "hours_per_week": 10,
  "study_mode": "self_study",
  "learning_style": ["visual", "reading"],
  "placement_decision": "take_now | skip"
}

---

Part III -- Workflow 2: Placement Test

7. Placement Test Briefing

Route: /student/placement Access: Authenticated, role = student Prerequisite: Onboarding wizard completed (account = activated)

7.1 Page Layout

Full-width card with:

• Subject selector (if student goal supports multiple subjects): shown only if the student's profile has Math or IT as goal. Default subject is pre-selected based on onboarding wizard goal.
• Test overview card: Subject name, estimated duration "20--30 minutes", dimension count "4 sections", adaptive note "The test adapts to your level -- questions get harder or easier based on your answers."
• Dimension breakdown table:

Dimension	Questions	Content	Duration
Grammar	~30 MCQ	Tenses, articles, prepositions, clauses	~8 min
Vocabulary	~20 items	Definition match, gap fill, collocations	~5 min
Reading	~10 Q / 2 passages	TF/NG, MCQ -- passages progress easy to difficult	~10 min
Speaking	3 prompts (optional)	Record 60-second responses	~5 min

• "Begin Test" button (primary, large)
• Note for entity students: "This test is mandatory. Your results will be shared with your institution."

7.2 Functional Requirements

ID	Requirement
BRIEF-01	For Math subject, the dimension breakdown changes to: Arithmetic (~20 MCQ), Algebra (~15 items), Geometry (~10 Q), Problem Solving (~10 Q). For IT: Computer Basics (~20 MCQ), Programming Logic (~15 items), Networking (~10 Q), Problem Solving (~10 Q).
BRIEF-02	"Begin Test" calls POST /api/placement/start which creates a CAT session and returns a session_id. Navigate to /student/placement/test?session={session_id}.
BRIEF-03	If an active placement session already exists (user refreshed), resume from where they left off.

---

8. CAT Test Interface

Route: /student/placement/test Access: Authenticated, role = student, active placement session Query Params: ?session={session_id}

8.1 Page Layout

Full-screen test interface with no navigation sidebar (distraction-free mode):

• Top bar: Timer (counting up, showing elapsed time), current section name (e.g., "Grammar"), progress indicator (question X of estimated ~Y), "Pause" button (if allowed)
• Main area: Question display area (adapts to question type)
• Bottom bar: "Previous" button (disabled for CAT -- no going back), "Next" / "Submit Answer" button, section progress dots

8.2 Question Type Renderers

Each question type requires a specific renderer component:

Question Type	Renderer	Used In
MCQ (single answer)	Radio button list with A/B/C/D labels	Grammar, Vocabulary, Reading
MCQ (multiple answers)	Checkbox list	Reading
Gap fill	Text input embedded in a sentence	Vocabulary
True/False/Not Given	3-option radio for each statement	Reading
Definition match	Drag-and-drop or select matching	Vocabulary
Audio recording	Microphone button, waveform display, playback, re-record	Speaking
Reading passage + questions	Split view: passage on left, questions on right (desktop). Scrollable passage above questions (mobile).	Reading

8.3 CAT-Specific Behaviour

ID	Requirement
CAT-01	After each answer submission, the frontend calls POST /api/placement/answer with the answer. The backend returns the next question (which may be harder or easier based on the IRT algorithm).
CAT-02	The frontend does NOT preload all questions. Each question is fetched one at a time from the backend. Show a brief loading spinner between questions (skeleton loader).
CAT-03	The progress indicator shows an estimated count (e.g., "Question 12 of ~30") because the CAT engine may terminate early if SEM reaches precision.
CAT-04	When the backend returns section_complete: true, show a transition screen: "Grammar section complete. Next: Vocabulary" with a 3-second countdown or "Continue" button.
CAT-05	The Speaking section shows a microphone permission prompt. If denied, skip the section with a note: "Speaking section skipped. Your placement will be based on the other three sections."
CAT-06	For speaking prompts, show: prompt text, a "Start Recording" button, a 60-second countdown timer, waveform visualizer during recording, "Stop" button, playback controls, "Re-record" option (max 1 re-record per prompt), and "Submit Recording" button.
CAT-07	Audio recordings are uploaded to the backend as blobs via POST /api/placement/speaking-upload.
CAT-08	On the final question of the last section, the "Submit" button shows "Finish Test". After clicking, navigate to /student/placement/results?session={session_id}.

8.4 Auto-Save

ID	Requirement
SAVE-01	All answers are auto-saved to the backend every 10 seconds via POST /api/placement/autosave.
SAVE-02	A small "Saved" indicator appears at the bottom of the screen after each successful auto-save.
SAVE-03	If the browser closes mid-test, the student can resume from the last saved position when they log in again.

8.5 API Contracts

Start session: POST /api/placement/start

{ "subject": "english | math | it" }

Response:

{ "session_id": "uuid", "first_question": { "id": 1, "type": "mcq", "section": "grammar", "stem": "...", "options": [...], "estimated_total": 30 } }

Submit answer: POST /api/placement/answer

{ "session_id": "uuid", "question_id": 1, "answer": "B", "time_spent_ms": 12340 }

Response:

{ "next_question": { ... }, "section_complete": false, "test_complete": false, "progress": { "current": 13, "estimated_total": 30 } }

Auto-save: POST /api/placement/autosave

{ "session_id": "uuid", "current_answer": { "question_id": 15, "answer": "C" } }

Upload speaking: POST /api/placement/speaking-upload (multipart/form-data) Fields: session_id, prompt_id, audio_file (blob)

---

9. Placement Results and Learning Path Preview

Route: /student/placement/results Access: Authenticated, role = student Query Params: ?session={session_id}

9.1 Page Layout

Results page with two main sections:

Section A -- Your Results

• Overall CEFR level displayed prominently (e.g., "B2" with a coloured badge)
• Per-dimension scores in a radar chart (Grammar, Vocabulary, Reading, Speaking)
• Score table:

Dimension	Score	CEFR Level	Gap to Target
Grammar	72%	B2	+0.5 to C1
Vocabulary	58%	B1	+1.0 to B2
Reading	65%	B2	+0.5 to C1
Speaking	Pending	--	AI evaluation in progress

• Note for entity students: If results_release_mode = manual_approval, show: "Your results are being reviewed by your institution. You will be notified when they are released." Hide the actual scores until approved.

Section B -- Your Personalised Learning Path

• Course outline card with estimated duration, module count, and study hours per week
• Skill gap modules listed by priority (largest gap first) with:
  • Module name
  • Estimated hours
  • Resource types (icons: PDF, Video, Audio, Exercise)
  • Difficulty level
• "View Full Course Plan" button -- expands to show detailed module breakdown
• Key design principle: This learning path is shown BEFORE any payment prompt.

9.2 Functional Requirements

ID	Requirement
RES-01	Results are fetched from GET /api/placement/results?session_id={id}.
RES-02	If Speaking evaluation is still in progress (speaking_status: "pending"), show a "Pending" badge. Poll GET /api/placement/speaking-status?session_id={id} every 30 seconds until complete. When complete, update the Speaking row in the table.
RES-03	The learning path preview is fetched from GET /api/placement/learning-path?session_id={id}.
RES-04	Entity students whose results are pending approval see a simplified view with a "Results Pending" message.
RES-05	For Math/IT subjects, CEFR levels are replaced with proficiency levels (Beginner/Intermediate/Advanced/Expert).
RES-06	"Continue" button at the bottom navigates to the payment/access page (Section 10).

---

10. Payment and Access Options

Route: /student/placement/access Access: Authenticated, role = student

10.1 Page Layout

Three pricing cards side by side:

Card	Title	Description	CTA
Full Access	"Unlock Full Course"	Full subscription or one-time payment. Complete access to all modules, AI tutoring, and practice exams.	"Subscribe Now"
Free Trial	"Try Free for 7 Days"	Limited access: first 3 modules only. Upgrade prompt after trial.	"Start Free Trial"
Skip	"Continue to Dashboard"	Dashboard access only. No course access. Prompted to subscribe later.	"Skip for Now"

10.2 Functional Requirements

ID	Requirement
PAY-01	"Subscribe Now" navigates to /student/subscription (existing subscription page).
PAY-02	"Start Free Trial" calls POST /api/subscription/trial and navigates to /student/dashboard.
PAY-03	"Skip for Now" navigates to /student/dashboard. A persistent banner appears on the dashboard: "Unlock your personalised course -- Subscribe now" with a dismiss option.
PAY-04	Entity students bypass this page entirely. Their access is controlled by the institution.

---

Part IV -- Workflow 3: Exam Configuration (International + Custom)

The platform supports two distinct exam template paths. Both paths share the same exam session, grading, and score release infrastructure (Part V). The key difference is who defines the exam structure.

11. Exam Template Paths

11.1 Two Paths Overview

Aspect	Path 1: International Templates	Path 2: Custom Templates
Examples	IELTS Academic, IELTS General Training, TOEFL, STEP, IC3	University midterm, entity-specific exam, department quiz
Who creates the template	EnCoach development team (pre-loaded during deployment)	Teacher or Entity Admin (via the platform UI)
Structure modifiable?	No -- parts, question counts, time limits, and skills are permanently locked	Yes -- fully configurable by the creator
Question assembly	Teacher fills fixed structural slots using Auto/Manual/Hybrid modes	Teacher adds questions freely to their own defined sections
Available to	All entities and individual students	Only the creating entity or teacher's students
Added via	Developer seeds template data into encoach.exam.template during module installation	Teacher/Admin uses the Custom Exam Creation UI (Section 16)

11.2 Template Selection Page

Route: /admin/exam/create Access: Authenticated, role = admin or teacher

The entry point for all exam creation is a template selection page:

• Section A -- International Exam Templates: A grid of cards showing pre-loaded templates (IELTS Academic, IELTS General Training, TOEFL, STEP, IC3). Each card shows: template name, icon, skill count, total questions, total time. A "Locked" badge indicates the structure cannot be modified. Clicking a card navigates to the international template wizard (Section 12).

• Section B -- Custom Exam: A single "Create Custom Exam" card with a plus icon. Clicking navigates to the custom exam creation form (Section 16).

11.3 Functional Requirements

ID	Requirement
TMPL-01	Available international templates are loaded from GET /api/exam/templates?type=international. Only templates with active = true are shown.
TMPL-02	The "Create Custom Exam" option is always available to teachers and admins.
TMPL-03	International template cards display a "Locked" badge and tooltip: "This exam structure is defined by the exam body and cannot be modified."

---

12. International Template -- IELTS Exam Initialization

Route: /admin/exam/ielts/create Access: Authenticated, role = admin or teacher

11.1 Page Layout

A step-by-step wizard (stepper component) with 5 phases matching the workflow document.

Phase 1 -- Exam Initialization Form

Field	Type	Validation	Notes
Exam Type	Toggle or radio	Required	Options: "IELTS Academic", "IELTS General Training"
Target Skills	Checkbox group (multi-select)	Required, at least one	Options: Listening, Reading, Writing, Speaking. Pre-checked: all four.
Exam Title	Text input	Required, max 200 chars	Auto-generated suggestion: "IELTS [Academic/General] -- [Date]"
Target Band	Slider	Required, 4.0--9.0 in 0.5 steps	Default: 6.5
Difficulty	Select	Required	Options: Easy, Medium, Hard. Mapped to band ranges.
Randomization	Toggle	Default: ON	"Randomize question order within each section"
Assembly Mode	Radio cards	Required	Auto: System builds entire exam from rules. Manual: Teacher handpicks every item. Hybrid: System suggests, teacher refines.
Score Release Mode	Radio	Required	Auto-release: Student sees results immediately. Manual approval: Entity admin must approve before student sees results.

11.2 Functional Requirements

ID	Requirement
IELTS-01	The exam structure (parts per skill, question counts per part) is fixed by the IELTS template and CANNOT be modified. A read-only info box shows: "IELTS Structure: Listening (4 parts, 40 Q), Reading (3 passages, 40 Q), Writing (2 tasks), Speaking (3 parts, 11-14 min)".
IELTS-02	"Next" button saves the initialization data via POST /api/exam/ielts/create and returns an exam_id. Navigates to Phase 2.
IELTS-03	Assembly mode selection changes the behaviour of Phase 3 (content retrieval).

11.3 API Contract

Create IELTS exam: POST /api/exam/ielts/create

{
  "exam_type": "academic | general_training",
  "skills": ["listening", "reading", "writing", "speaking"],
  "title": "string",
  "target_band": 6.5,
  "difficulty": "easy | medium | hard",
  "randomize": true,
  "assembly_mode": "auto | manual | hybrid",
  "results_release_mode": "auto | manual_approval"
}

---

13. Per-Skill Configuration Panels

Route: /admin/exam/ielts/:examId/skills Access: Authenticated, role = admin or teacher

12.1 Page Layout

Tabbed interface with one tab per selected skill. Each tab shows the fixed structure for that skill:

Listening Tab

Part	Questions	Content Type	Time
Part 1	10	Conversation (2 speakers, everyday context)	~6 min
Part 2	10	Monologue (social/everyday context)	~6 min
Part 3	10	Conversation (2-4 speakers, academic context)	~6 min
Part 4	10	Monologue (academic lecture)	~8 min

Reading Tab (Academic)

Passage	Questions	Text Type
Passage 1	13--14	Factual/descriptive
Passage 2	13--14	Discursive/analytical
Passage 3	13--14	Complex argumentative

Reading Tab (General Training)

Section	Questions	Text Type
Section 1	13--14	Short texts (everyday)
Section 2	13--14	Workplace texts
Section 3	13--14	General interest (longer)

Writing Tab

Task	Type	Min Words
Task 1	Academic: describe visual data. General: write a letter.	150
Task 2	Essay (both types)	250

Speaking Tab

Part	Duration	Format
Part 1	4--5 min	Familiar topic questions
Part 2	3--4 min	Cue card long turn (1 min prep + 2 min speaking)
Part 3	4--5 min	Abstract discussion linked to Part 2 topic

12.2 Functional Requirements

ID	Requirement
SKILL-01	The structure tables above are READ-ONLY. The teacher/admin cannot change the number of parts, questions per part, or time limits. These are fixed IELTS template values.
SKILL-02	Each skill tab shows the available content pool count: "Available: 245 questions for Listening Part 1". Fetched from GET /api/exam/ielts/:examId/content-pool-count.
SKILL-03	A "Configure Content" button on each tab navigates to the content pool view (Section 13) for that specific skill/part.
SKILL-04	A summary panel on the right shows overall exam completion status: how many questions are filled vs required per skill.

---

14. Content Pool and Question Assembly

Route: /admin/exam/ielts/:examId/content Access: Authenticated, role = admin or teacher

13.1 Page Layout

Split view:

• Left panel (60%): Content pool browser with filters
• Right panel (40%): Selected questions for the current section

Content Pool Browser

Filter	Type	Options
Skill	Dropdown	Listening, Reading, Writing, Speaking
Part	Dropdown	Depends on skill (e.g., Part 1--4 for Listening)
Difficulty	Slider	Easy / Medium / Hard
Topic	Multi-select tags	Loaded from backend
Status	Checkbox	Available, Seen (by this student), Flagged, Retired
Search	Text input	Search question text/stem

Content items displayed as cards with: preview text (truncated), difficulty badge, topic tags, usage count, quality rating.

Assembly Behaviour by Mode

Mode	Left Panel	Right Panel
Auto	Greyed out (system selects automatically). "System has selected 40 questions. Review below."	Shows system-selected questions. Teacher can "Swap" individual items.
Manual	Full browsing. Teacher clicks "Add" on each item.	Shows teacher-selected items with drag-and-drop reordering. Count badge: "12/40 selected".
Hybrid	System pre-populates suggestions (highlighted). Teacher can accept, reject, or swap.	Shows suggested items. "Accept All" or individual accept/reject buttons.

13.2 Functional Requirements

ID	Requirement
POOL-01	The content pool is fetched from GET /api/exam/ielts/:examId/content-pool with filter parameters. Returns 3--5x more items than needed.
POOL-02	Content filters exclude: items seen by the assigned student (if student is specified), flagged items, retired items. Topic diversity and difficulty curve are applied by the backend.
POOL-03	In Auto mode, POST /api/exam/ielts/:examId/auto-assemble triggers the backend to select questions. Frontend displays the result and allows the teacher to swap items.
POOL-04	In Manual mode, the right panel tracks a running count. The teacher cannot proceed until all structural slots are filled (e.g., 40/40 for Listening).
POOL-05	In Hybrid mode, POST /api/exam/ielts/:examId/suggest returns suggested items. Teacher reviews and confirms.
POOL-06	"Save & Continue" persists the selection via PUT /api/exam/ielts/:examId/sections/:sectionId/questions.

---

15. Exam Assembly and Validation

Route: /admin/exam/ielts/:examId/validate Access: Authenticated, role = admin or teacher

14.1 Page Layout

Full exam preview with validation report:

Validation Checklist

Check	Status	Description
Question Count	Pass/Fail	"Listening: 40/40, Reading: 40/40, Writing: 2/2, Speaking: 3 parts"
Media URLs	Pass/Fail	All audio files and images are accessible
Answer Keys	Pass/Fail	All auto-scored items have correct answers defined
No Duplicates	Pass/Fail	No question appears in multiple sections
Rubrics	Pass/Fail	Writing and Speaking tasks have rubrics linked
Time Specification	Pass/Fail	Each section has a valid time limit

• Red items block publishing. Yellow items are warnings (can proceed with acknowledgement).
• "Preview Exam" button opens a read-only student-view preview of the exam.

Teacher Review Panel (Manual/Hybrid only)

• Expandable sections per skill with all selected questions
• Swap, reorder, replace actions per question
• Inline passage/audio preview

Publish Actions

Button	Action
"Save as Draft"	PUT /api/exam/ielts/:examId with status: "draft"
"Publish"	PUT /api/exam/ielts/:examId with status: "published". Only enabled if all validation checks pass.
"Assign to Students"	Opens a student/batch selector dialog. Calls POST /api/exam/ielts/:examId/assign.

14.2 Functional Requirements

ID	Requirement
VAL-01	Validation runs automatically when the page loads via GET /api/exam/ielts/:examId/validate.
VAL-02	After publishing, the exam is locked for editing. A "Duplicate" option allows creating a copy for modification.
VAL-03	"Assign to Students" shows a searchable student list and batch list. Multiple students and batches can be selected. Each assignment includes an optional access window (start date, end date).

---

16. Custom Template -- Exam Creation

Route: /admin/exam/custom/create Access: Authenticated, role = admin or teacher

16.1 Page Layout

A form-based exam builder where the teacher defines the entire exam structure from scratch.

Step 1 -- Exam Properties

Field	Type	Validation	Notes
Exam Title	Text input	Required, max 200 chars
Subject	Select	Required	Loaded from taxonomy: English, Mathematics, IT, etc.
Description	Textarea	Optional	Exam purpose and instructions for students
Total Time	Number (minutes)	Required, min 5	Overall exam duration
Pass Threshold	Percentage slider	Optional, 0--100	Minimum score to pass. If not set, no pass/fail routing.
Score Release Mode	Radio	Required	Auto-release: student sees results immediately. Manual approval: entity admin must approve.
Randomize Questions	Toggle	Default: OFF	Randomize question order for each student

Step 2 -- Section Builder

The teacher adds one or more sections. Each section is a collapsible panel:

Field	Type	Validation	Notes
Section Title	Text input	Required	e.g., "Part A -- Grammar", "Section 2 -- Essay"
Skill/Category	Select	Optional	Tag this section with a skill (Listening, Reading, Writing, Speaking, Grammar, Vocabulary, or custom label)
Question Count	Number	Required, min 1	How many questions this section will contain
Time Limit	Number (minutes)	Optional	Per-section time limit. If not set, section shares the overall exam timer.
Scoring Method	Select	Required	Auto-scored: MCQ, gap fill, TF/NG (system grades automatically). Rubric-scored: Writing, Speaking (teacher or AI grades). Mixed: section contains both types.

• "Add Section" button: adds a new section panel
• Sections can be reordered via drag-and-drop
• Sections can be deleted (with confirmation dialog)

Step 3 -- Question Assignment

For each section, the teacher adds questions using the same content pool browser (Section 14) or by creating new questions inline:

• "Browse Content Pool" button: opens the shared content pool with filters (subject, skill, difficulty, topic)
• "Create New Question" button: opens an inline question form (question type, stem, options, correct answer, marks, difficulty)
• Running count: "8/10 questions added"
• The teacher can add questions beyond the defined count (extras are held as alternates for randomization)

Step 4 -- Review and Publish

Same validation and publish flow as Section 15 (Exam Assembly and Validation), but the validation rules adapt:

• Question count per section must meet the defined minimum
• If scoring method is "Rubric-scored", rubrics must be linked
• Time limits must be valid
• Answer keys must exist for all auto-scored questions

16.2 Functional Requirements

ID	Requirement
CUSTOM-01	Custom exam creation calls POST /api/exam/custom/create with the full exam structure (properties + sections + questions). Returns an exam_id.
CUSTOM-02	There are NO locked structural constraints. The teacher has full control over section count, question count, time limits, and skill assignments.
CUSTOM-03	Custom exams are scoped to the creating teacher's entity. If the teacher has no entity, the exam is personal (visible only to that teacher's students).
CUSTOM-04	Custom exams use the same exam session interface (Section 17), grading pipeline (Section 18), score release gate (Section 18), and results display (Section 19) as international template exams.
CUSTOM-05	A "Save as Template" option allows the teacher to save a custom exam structure as a reusable template for future exams. This creates a record in encoach.exam.template with editable = true and type = custom.
CUSTOM-06	"My Templates" section on the template selection page (Section 11.2) shows the teacher's saved custom templates.

16.3 API Contracts

Create custom exam: POST /api/exam/custom/create

{
  "title": "UTAS English Midterm -- Spring 2026",
  "subject_id": 1,
  "description": "...",
  "total_time_min": 90,
  "pass_threshold": 60,
  "results_release_mode": "auto",
  "randomize": false,
  "sections": [
    {
      "title": "Part A -- Grammar",
      "skill": "grammar",
      "question_count": 20,
      "time_limit_min": 30,
      "scoring_method": "auto",
      "question_ids": [101, 102, 103]
    },
    {
      "title": "Part B -- Writing",
      "skill": "writing",
      "question_count": 2,
      "time_limit_min": 60,
      "scoring_method": "rubric",
      "question_ids": [201, 202]
    }
  ]
}

Save as template: POST /api/exam/templates/custom

{
  "name": "UTAS English Midterm Template",
  "structure": { "sections": [...] },
  "editable": true,
  "type": "custom"
}

Get teacher's custom templates: GET /api/exam/templates?type=custom

---

Part V -- Workflow 4: General English Exam

17. Exam Session Interface

Route: /student/exam/:examId/session Access: Authenticated, role = student, exam assigned to this student

15.1 Page Layout

Full-screen distraction-free interface (no sidebar, minimal header):

• Top bar: Exam title, current section name, section timer (countdown), overall progress bar
• Main area: Question renderer (varies by question type -- see Section 8.2 for renderers)
• Bottom bar: "Previous" button, "Next" button, "Flag for Review" button, "Submit Section" button (on last question of section)
• Section transitions: Brief screen between sections showing: "Section Complete. Next: [Section Name]. Time limit: [X minutes]."

15.2 Functional Requirements

ID	Requirement
EXAM-01	The exam is loaded from GET /api/exam/:examId/session. Returns all sections, time limits, and questions (pre-loaded, unlike CAT).
EXAM-02	Each section has its own countdown timer. When time expires, answers for that section are auto-submitted and the student moves to the next section. Warning at 5 minutes and 1 minute remaining.
EXAM-03	Answers are auto-saved every 10 seconds via POST /api/exam/:examId/autosave.
EXAM-04	"Flag for Review" marks a question with a flag icon. Flagged questions appear in a review panel before final submission.
EXAM-05	Before final submission, show a review summary: answered count, unanswered count, flagged count, per section. "Submit Exam" button confirms submission.
EXAM-06	After submission, navigate to a "Submission Confirmation" page. If results_release_mode = auto, show results immediately (Section 17). If manual_approval, show "Your exam has been submitted. Results will be available after review."
EXAM-07	For Writing tasks: rich text editor with word count. Minimum word count indicator (turns red below 150 for Task 1, below 250 for Task 2).
EXAM-08	For Speaking tasks: audio recording interface (same as placement test -- Section 8.2).
EXAM-09	For Listening tasks: audio player with play/pause, progress bar, volume control. Audio plays once (IELTS standard). Replay is NOT allowed unless the exam is configured for practice mode.

---

18. Grading and Score Release

Route: /student/exam/:examId/status (student view) Route: /admin/exam/:examId/grading (admin/teacher view)

16.1 Student View

State	Display
Submitted, auto-scoring in progress	"Your Listening and Reading scores are being calculated..." (spinner)
L/R scored, W/S pending teacher review	Show L/R band scores. W/S shows "Pending Review" with estimated wait time.
Fully scored, release = auto	Show all scores immediately (Section 17).
Fully scored, release = manual_approval	"Your results are complete and under review by your institution. You will be notified when they are released."
Released by admin	Show all scores (Section 17).

16.2 Admin/Teacher Grading Queue

Page layout: Table of submissions pending grading.

Column	Content
Student Name	Link to student profile
Exam Title	Link to exam config
Skill	Writing or Speaking (the skill needing manual grading)
Submitted At	Timestamp
Status	"Pending" / "In Progress" / "Graded"
Action	"Grade Now" button

Grading Interface: When "Grade Now" is clicked, show:

• Student's response (essay text for Writing, audio playback for Speaking)
• Rubric criteria panel with score selectors for each criterion
• For IELTS Writing: Task Achievement, Coherence and Cohesion, Lexical Resource, Grammatical Range and Accuracy (each scored 0--9)
• For IELTS Speaking: Fluency and Coherence, Lexical Resource, Grammatical Range and Accuracy, Pronunciation (each scored 0--9)
• "AI Grade Suggestion" button: calls POST /api/grading/ai-suggest and populates the rubric with AI-suggested scores. Teacher can accept or override.
• "Submit Grade" button: saves the score and moves to the next submission in the queue.

---

19. Results Display and Reporting

Route: /student/exam/:examId/results Access: Authenticated, role = student, results released

17.1 Page Layout

Score Summary Card

• Overall Band Score (large, prominent): e.g., "6.5"
• CEFR Equivalent: e.g., "C1 -- Effective Operational Proficiency"
• Per-Skill Radar Chart: Listening, Reading, Writing, Speaking on four axes
• Per-Skill Table:

Skill	Band	CEFR	Gap to Target
Listening	7.0	C2	--
Reading	6.0	C1	+1.0
Writing	5.5	B2	+1.5
Speaking	6.5	C1	+0.5

Feedback Section

• Per-question feedback (expandable accordions per section)
• Weak areas highlighted with recommendations
• "Areas to improve" summary: top 3 weakness areas with linked learning resources

Actions

• "Download PDF Report" button: generates PDF with QR code (Section 36)
• "View Recommended Course" button: navigates to course generation (Section 19)
• "Retake Exam" button (if practice mode): creates a new exam attempt

---

20. Result Routing

Embedded within the results page (Section 17), a prominent action card at the bottom:

18.1 Pass / Sufficient Score Path

Card title: "Congratulations! You've reached your target."

• "Register for Official IELTS Exam" button -- navigates to /student/exam-registration
• "Continue Studying" button -- navigates to /student/dashboard

18.2 Below Threshold Path

Card title: "Let's build a plan to reach your target."

• "Start Adaptive Training" button -- navigates to /student/course/generate?from=exam&examId={id}
• Skill gap summary shown inline (from gap analysis)
• Teacher notification note: "Your teacher has been notified of your results."

---

Part VI -- Workflow 5: Course Generation

21. Gap Analysis Dashboard

Route: /student/course/generate Access: Authenticated, role = student (individual path) or admin/teacher (entity path) Query Params: ?from=exam&examId={id} or ?from=placement&sessionId={id}

19.1 Page Layout

Skill Gap Visualization

• Bar chart: Skills ranked by gap size (largest first). Each bar shows current level vs target.
• Table view:

Skill	Current	Target	Gap	Priority	Est. Hours
Writing	5.5 (B2)	7.0 (C2)	1.5	High	40
Reading	6.0 (C1)	7.0 (C2)	1.0	Medium	25
Speaking	6.5 (C1)	7.0 (C2)	0.5	Low	15
Listening	7.0 (C2)	7.0 (C2)	0.0	--	0

• Question-type weaknesses: Expandable per skill. Shows error rate per question type (e.g., "MCQ: 85% correct, Gap Fill: 42% correct").
• Topic weaknesses: Grouped by category (e.g., "Environment: 3/5 wrong, Technology: 1/5 wrong").

19.2 Functional Requirements

ID	Requirement
GAP-01	Gap analysis is fetched from `GET /api/course/gap-analysis?source={exam
GAP-02	For individual students, the "Generate Course" button is shown. Clicking it triggers automatic course structure generation (Section 20).
GAP-03	For entity students, the page is view-only. A message states: "Your teacher will configure your course based on these results."

---

22. Course Structure Configuration

Route: /admin/course/configure/:courseId (entity path) or /student/course/configure/:courseId (individual path)

20.1 Individual Student Path (Auto-Generated)

The system auto-generates a course structure. The student sees a read-only preview:

• Course title (auto-generated: e.g., "IELTS Preparation -- Writing & Reading Focus")
• Duration estimate
• Module list with skill assignments, hours, and resource type icons
• "Start Course" button -- begins the course immediately
• "Customize" button (optional) -- allows minor adjustments (reorder modules, skip low-priority skills)

20.2 Entity/Teacher Path (Manual Configuration)

Admin/Teacher configurable form:

Field	Type	Validation
Course Title	Text input	Required
Exam Type	Select	IELTS Academic, IELTS General Training, General English
Target Band/Level	Slider/Select	Required
Duration	Number (weeks)	Required, 1--52
Study Hours/Week	Slider	Required, 1--40
Skills	Checkbox group	Pre-selected from gap analysis (gap >= 1.0). Teacher can override.
Skill Weightings	Sliders per skill	Hours per skill. Informed by gap size. Must sum to total estimated hours.
Progression Model	Radio cards	Linear: Fixed module order. Parallel: All sections active simultaneously. Adaptive: Engine manages order based on performance.

20.3 Functional Requirements

ID	Requirement
COURSE-01	Individual path: POST /api/course/auto-generate with source_id (exam or placement session). Returns a pre-built course structure.
COURSE-02	Entity path: POST /api/course/create with teacher-configured parameters. Returns a course_id for module building.
COURSE-03	Progression model "Adaptive" requires the adaptive engine to be active. If not yet deployed, show a note: "Adaptive mode will be available after the engine is deployed. Defaulting to Parallel."

---

23. Module Builder

Route: /admin/course/:courseId/modules Access: Authenticated, role = admin or teacher

21.1 Page Layout

Each skill section is a collapsible panel containing its modules:

Writing Section (40 hours, 5 modules)
  ├── Module 1: Task Achievement Basics (8h)
  │     └── Resources: [PDF] [Video] [Exercise] [AI-Generated]
  ├── Module 2: Coherence and Cohesion (8h)
  │     └── Resources: [PDF] [Exercise]
  └── ... more modules
Reading Section (25 hours, 3 modules)
  ├── Module 1: Skimming and Scanning (10h)
  └── ...

Module Configuration

Field	Type	Notes
Module Title	Text input	Required
Estimated Hours	Number	Required
Resources	Resource attachment panel	Browse and attach: PDF, Video, Audio, Exercise, AI-generated content. Uses shared content database.
Practice Exercises	Exercise builder	Add practice questions with answer keys.
Completion Criteria	Select	Options: "Complete all resources", "Score 70%+ on exercises", "Teacher approval"
Prerequisite Module	Select (optional)	For linear/adaptive progression

21.2 Functional Requirements

ID	Requirement
MOD-01	Resources are selected from the shared content database via a search/browse modal. GET /api/resources?skill={skill}&difficulty={level}&type={type}.
MOD-02	AI-generated resources can be requested inline: "Generate AI Content" button opens a brief form (topic, difficulty, type) and calls POST /api/ai/generate-resource.
MOD-03	Modules can be reordered via drag-and-drop.
MOD-04	"Publish Course" button on the module builder page publishes the course and assigns it to the student(s). Calls PUT /api/course/:courseId with status: "published".

---

24. Course Delivery and Progress

Route: /student/course/:courseId Access: Authenticated, role = student

22.1 Student Course View

• Course header: Title, overall progress percentage, estimated time remaining
• Module list: Collapsible sections per skill. Each module shows:
  • Title, status (locked/available/in-progress/completed), progress bar
  • Resource list with type icons and completion checkmarks
  • "Start" / "Continue" button
• Adaptive indicators (when progression = Adaptive):
  • "Recommended Next" badge on the module the engine suggests
  • "Unlocked!" animation when a new module becomes available
  • "Skipped" badge if the engine determines the student doesn't need a module (95%+ score)

22.2 Resource Viewer

In-platform viewers for each content type:

Type	Viewer	Implementation
PDF	Embedded PDF viewer (browser native or react-pdf)	Full-screen overlay or inline
Video	HTML5 <video> player with controls	Inline with progress tracking
Audio	HTML5 <audio> player with waveform	Inline
Exercise	Interactive question renderer (same components as exam)	Inline with submit/check
AI-generated	Rendered text/HTML content	Inline

22.3 Progress Dashboard (Teacher View)

Route: /teacher/course/:courseId/progress

Table of enrolled students with:

Column	Content
Student Name	Link to student detail
Overall Progress	Progress bar (%)
Current Module	Module name
Time Spent	Total hours
Predicted Band Improvement	AI-estimated band gain (e.g., "+1.0")
Last Activity	Timestamp
Alert	"No progress for 3+ days" warning icon

22.4 Post-Course Assessment

When a student completes all modules:

• Completion celebration screen
• "Take Post-Course Assessment" button: assigns a new practice exam (same type as the diagnostic exam) to measure improvement
• Results comparison: side-by-side pre-test vs post-test scores

22.5 Functional Requirements

ID	Requirement
DELIVER-01	Course data is fetched from GET /api/course/:courseId. Includes all sections, modules, resources, and student progress.
DELIVER-02	Resource completion is tracked via POST /api/course/:courseId/progress with resource_id, completion_percent, and time_spent_ms.
DELIVER-03	Checkpoint exercises trigger scoring via POST /api/course/:courseId/checkpoint. If the score is below the threshold, the engine may insert remedial resources.
DELIVER-04	The post-course exam is assigned via POST /api/course/:courseId/post-test.

---

Part VII -- Workflow 6: Entity Student Onboarding

25. Admin Bulk Upload Interface

Route: /admin/entity/students/upload Access: Authenticated, role = admin or corporate or mastercorporate

23.1 Page Layout

Step 1 -- Upload

• File upload zone: Drag-and-drop or click-to-browse. Accepts .csv files only.
• Download Template link: downloads a sample CSV with headers: student_name, institutional_email, national_id, student_id, enrolled_programme
• Upload button: "Upload & Validate"

Step 2 -- Validation Report

After upload, the backend validates the CSV and returns a report:

Column	Content
Row #	Row number in CSV
Student Name	Name from CSV
Email	Email from CSV
Status	"Valid" (green check) / "Error" (red X) / "Warning" (yellow !)
Issue	Error description (e.g., "Duplicate email", "Missing required field: national_id", "Invalid email format")

• Summary bar: "247 valid, 3 errors, 1 warning"
• "Fix & Re-upload" button: allows the admin to download the error rows, fix them, and re-upload
• "Confirm & Create Accounts" button: only enabled if there are zero errors (warnings are allowed). Calls POST /api/entity/students/bulk-create.

Step 3 -- Confirmation

• Success message: "248 student accounts created successfully."
• Table of created accounts with: name, email, default password indicator ("National ID"), status ("Pending First Login")
• "Send Credential Emails" button: triggers POST /api/entity/students/send-credentials. Sends notification emails to all newly created students.

23.2 Functional Requirements

ID	Requirement
BULK-01	CSV validation is done on the backend via POST /api/entity/students/validate-csv (multipart/form-data). Returns validation report JSON.
BULK-02	Bulk account creation: username = institutional email, default password = national ID number. All accounts tagged with the admin's entity_id.
BULK-03	CAPTCHA is NOT required for entity bulk-upload accounts.
BULK-04	The admin can optionally set a "Bypass Placement" flag for specific students (e.g., Year 2 students who already have a known level).
BULK-05	SIS integration (if entity has SIS configured): show an "Import from SIS" tab alongside the CSV upload tab. This calls POST /api/entity/students/sis-import.

---

26. Credential Delivery Dashboard

Route: /admin/entity/students/credentials Access: Authenticated, role = admin or corporate or mastercorporate

24.1 Page Layout

Table of entity students with credential delivery status:

Column	Content
Student Name	Text
Email	Text
Account Status	"Pending First Login" / "Active" / "Password Reset Required"
Email Sent	Yes/No with timestamp
First Login	Yes/No with timestamp
Placement Status	"Not Started" / "In Progress" / "Completed" / "Bypassed"

Filters: Account Status, Email Sent, Placement Status, Date range.

Actions:

• "Resend Email" button per row: calls POST /api/entity/students/:id/resend-credentials
• "Resend All Pending" button: calls POST /api/entity/students/resend-all-pending
• Bulk actions: Select multiple rows, "Resend Selected"

---

27. Entity Student First Login

Route: /reset-password (triggered automatically on first login) Access: Authenticated, first_login = true

25.1 Page Layout

Centered card with:

• Heading: "Welcome to [Entity Name]'s Learning Platform"
• Subtext: "For security, please set a new password before continuing."
• Fields: New Password (with strength indicator), Confirm Password
• "Set Password & Continue" button

25.2 Functional Requirements

ID	Requirement
FIRST-01	When the system detects first_login = true on any login, redirect to /reset-password. No other page is accessible until password is reset.
FIRST-02	After password reset, first_login is set to false. The student is redirected to /student/placement (mandatory placement test).
FIRST-03	No onboarding wizard is shown to entity students. They go directly from password reset to placement test.
FIRST-04	Entity branding (logo, colours) is applied to this page if white-labelling is configured.

---

Part VIII -- AI Course Generation

28. General English AI Course Generation

Route: /student/course/ai-english/:courseId Access: Authenticated, role = student

26.1 Student Profile and Goal Setting

Before the AI course begins, a confirmation screen shows:

• Current CEFR Level: (from placement test results, e.g., "B1")
• Target CEFR Level: (e.g., "B2") -- editable
• Learning Style: (from onboarding wizard) -- editable
• Estimated Duration: (calculated based on gap and study hours/week)
• "Start AI Course" button: calls POST /api/ai-course/english/create

26.2 Content Taxonomy Browser (Teacher/Admin)

Route: /admin/ai-course/english/taxonomy

Read-only taxonomy reference showing what the AI uses to generate content:

Dimension	Description	Examples
Grammar Topics by CEFR	Grammar points per level	A1: present simple; B2: conditionals, passive voice; C1: inversion
Vocabulary Bands	Frequency tiers	High-freq 1000-3000, Academic Word List, topic-specific
Skill Areas	Content types per skill	Reading fluency, Writing practice, Speaking fluency, Listening comprehension
Topic Categories	Real-world subjects	Daily life, work, travel, technology, culture, environment

26.3 AI Generation Progress (Student View)

While the AI generates content:

• Progress indicator: "Generating your personalised course... Step 2/5: Creating grammar exercises"
• Steps: Profile Analysis, Reading Content, Grammar Exercises, Speaking Prompts, Vocabulary Sets
• Estimated time: "This usually takes 1--2 minutes"

26.4 Quality Gate Status (Admin/Teacher View)

Route: /admin/ai-course/english/:courseId/quality

Check	Status	Detail
Readability Score	Pass/Fail	"Flesch-Kincaid: 65 (target B2 range: 60-70)"
CEFR Calibration	Pass/Fail	"Content difficulty matches B2 level"
Grammar Accuracy	Pass/Fail	"No grammar errors detected in generated content"
Length Compliance	Pass/Fail	"All passages within 200-400 word range"

• "Approve" button: marks content as approved, available for the student
• "Reject & Regenerate" button: sends content back to AI with error notes (max 3 attempts)
• "Edit" button: opens content in an inline editor for manual correction

26.5 Autonomous Course Delivery (Student View)

Three parallel module tracks displayed as columns:

┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│   Grammar    │  │    Skills   │  │  Vocabulary  │
│  Track       │  │    Track    │  │    Track     │
├─────────────┤  ├─────────────┤  ├─────────────┤
│ ✅ Mod 1    │  │ ✅ Mod 1    │  │ 🔄 Mod 1    │
│ 🔄 Mod 2    │  │ ⬜ Mod 2    │  │ ⬜ Mod 2    │
│ ⬜ Mod 3    │  │ ⬜ Mod 3    │  │ ⬜ Mod 3    │
└─────────────┘  └─────────────┘  └─────────────┘

• Grammar Track: Explanations, exercises, and worked examples
• Skills Track: Reading/Writing/Speaking tasks at CEFR level
• Vocabulary Track: Contextual word learning with spaced repetition

Each module shows: title, completion status, estimated time, "Start" / "Continue" button.

When a level is achieved, a celebration modal: "You've reached B2! Ready for the next level?" with options to level up or take a reassessment.

26.6 Progress Report

• CEFR gain chart (before vs after)
• Time spent per track
• Module completion rates
• "Next Level" recommendation

---

29. AI IELTS Course Generation

Route: /student/course/ai-ielts/:courseId Access: Authenticated, role = student

27.1 IELTS Gap Profile Display

Before the AI IELTS course begins, a profile summary:

• Exam Type: Academic or General Training
• Current Bands: Per skill (from placement/diagnostic exam)
• Target Band: (editable)
• Skills ranked by gap size: Largest gap = highest priority (visual ranking)
• Weak question types: Per skill (e.g., "Reading: TFNG accuracy 40%, Gap Fill accuracy 55%")
• "Start AI IELTS Course" button

27.2 AI Content Generation Per Skill

While content is generated, a per-skill progress panel:

Skill	Status	Detail
Listening	Generating...	"Creating audio scripts for Parts 1-4"
Reading	Complete	"3 passages generated with 40 questions"
Writing	In Quality Check	"Validating Task 1 and Task 2 prompts"
Speaking	Complete	"Cue cards and question sets ready"

27.3 IELTS Standards Validation Status (Admin View)

Route: /admin/ai-course/ielts/:courseId/validation

This is the unique two-layer validation pipeline. The admin sees:

Layer 1 -- Automated IELTS Standards Check

Check	Status	Detail
Format Compliance	Pass/Fail	Word counts within IELTS ranges, correct part structure, question type matches spec
CEFR Band Calibration	Pass/Fail	Readability mapped to target band, difficulty matches band descriptor
Answer Key Completeness	Pass/Fail	All auto-scored items have correct answers, W/S rubrics linked with 4 criteria

If any check fails, an error detail panel shows specific issues: "Reading Passage 2: word count 890 -- exceeds IELTS maximum of 850 words."

Layer 2 -- IELTS Examiner Review Queue

Table of content items pending examiner review:

Column	Content
Skill	Listening/Reading/Writing/Speaking
Content Type	Passage/Audio Script/Prompt/Cue Card
Target Band	Band level
Generated At	Timestamp
Examiner	Assigned examiner (or "Unassigned")
Status	"Pending Review" / "Approved" / "Rejected"
Action	"Review" button

Review Interface:

• Full content preview
• Examiner checklist: accuracy of topic/context, appropriateness of difficulty, alignment with real IELTS conditions, cultural sensitivity
• "Approve" (marks as ielts_certified = true) or "Reject with Notes" (returns to AI for regeneration)

Content source gate: AI-generated content requires mandatory examiner review. Content uploaded by an IELTS-certified entity shows "Spot-check only" status.

27.4 IELTS Course Delivery (Student View)

Four parallel skill paths displayed as columns:

┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│ Writing  │  │ Reading  │  │ Speaking │  │ Listening│
│ Path     │  │ Path     │  │ Path     │  │ Path     │
├──────────┤  ├──────────┤  ├──────────┤  ├──────────┤
│ T1+T2    │  │ 3 Sets   │  │ P1/P2/P3 │  │ P1-P4   │
│ + Models │  │ + Full Q │  │ + Cue    │  │ + Audio  │
│ + Rubric │  │          │  │ + Model  │  │ + Q Sets │
└──────────┘  └──────────┘  └──────────┘  └──────────┘

27.5 Practice Exam and Readiness Check

When the adaptive engine determines the target band is likely reached:

• Modal: "Your performance suggests you're ready for band [X]. Take a full practice exam to confirm?"
• "Take Practice Exam" button -- assigns a full IELTS practice exam
• After the practice exam, if band confirmed: "You've reached your target! Register for the official IELTS exam?"
• If not yet reached: "Almost there! The AI has generated harder content for your next set of modules."

27.6 Progress Report

• Band improvement per skill (before vs after chart)
• Modules completed count
• Total time spent
• Weak area evolution (how weak areas improved over time)
• "Recommended next step" action card

---

Part IX -- Adaptive Learning Engine UI

30. Adaptive Engine Dashboard

Route: /admin/adaptive/dashboard Access: Authenticated, role = admin

28.1 Engine Status Overview

Metric	Display
Active Students	Count of students currently in adaptive courses
Engine Phase	Current implementation phase (1: Rule-based, 2: IRT-CAT, 3: Collaborative, 4: Full ML)
Decisions Today	Count of adaptive decisions made today
Average Improvement	Average band/CEFR improvement across all students
Alerts	Count of "no progress 3+ days" alerts

28.2 Student Adaptive Profiles (Admin View)

Table of students with adaptive learning data:

Column	Content
Student	Name, link to profile
Subject	English/IELTS/Math/IT
Current Level	CEFR or band
Target Level	CEFR or band
Days Active	Count
Last Decision	"Served harder content" / "Inserted micro-lesson" / "Skipped module"
Progress Trend	Sparkline (mini chart)
Alert	Warning icon if no progress 3+ days

28.3 Teacher Threshold Configuration

Route: /teacher/adaptive/settings

For Phase 1 (rule-based engine), teachers set explicit thresholds:

Setting	Type	Default	Description
Difficulty Step-Up Threshold	Percentage	85%	If student scores above this, serve harder content
Difficulty Step-Down Threshold	Percentage	50%	If student scores below this, serve easier content
Micro-Lesson Trigger	Number	2	Insert a micro-lesson if student is stuck N+ times on a topic
Module Skip Threshold	Percentage	95%	Skip module if pre-test score is above this
No-Progress Alert Days	Number	3	Alert teacher if student has no progress for N days
Max Retries per Exercise	Number	3	Maximum retries before flagging for teacher review

28.4 Functional Requirements

ID	Requirement
ADAPT-01	Dashboard data is fetched from GET /api/adaptive/dashboard.
ADAPT-02	Student profiles are fetched from GET /api/adaptive/students?page={n}&limit={m}.
ADAPT-03	Teacher thresholds are saved via PUT /api/adaptive/settings.
ADAPT-04	No-progress alerts trigger a visual badge on the teacher sidebar and an optional email notification.

---

31. Engine Signals and Decision Visualization

Route: /admin/adaptive/student/:studentId Access: Authenticated, role = admin or teacher

29.1 Signal Timeline

A timeline of all engine signals for a specific student:

Time	Signal	Value	Decision Made
10:32	Quiz score	92%	Serve harder content
10:45	Time on task	3 min (fast)	Confirm difficulty increase
11:00	Quiz score	45%	Revert to easier content
11:15	Retry count	3	Insert micro-lesson
14:00	Module completion	Module 3	Unlock Module 4

Signals read by the engine (from workflow document):

• Quiz scores, error rate, retry count, time on task, video completion, study time patterns, module completion, band delta, past attempt history, CAT placement results.

Decisions made by the engine:

• Next content to serve, difficulty adjustment, resource type matching to learning style, micro-lesson insertion, module skip, teacher alert.

29.2 Ability Model (Phase 2+)

For IRT-based phases, show the student's ability estimate:

• Ability estimate (theta): Current IRT ability value per skill
• Standard Error of Measurement (SEM): Confidence in the estimate
• Ability trajectory chart: Line chart showing theta over time

---

Part X -- Entity Management and White-Labelling

32. Entity Level Mapping Configuration

Route: /admin/entity/:entityId/level-mapping Access: Authenticated, role = admin or mastercorporate

30.1 Page Layout

Configuration table for mapping CEFR scores to institutional levels:

CEFR Min Score	CEFR Max Score	Internal Level Name	CEFR Equivalent
0	29	Foundation	Pre-A1
30	49	Level 1	A1--A2
50	69	Level 2	B1--B2
70	84	Level 3	C1
85	100	High Flyer	C2

• Editable rows with inline editing
• "Add Row" button to add new mappings
• "Save" button: PUT /api/entity/:entityId/level-mapping
• "Reset to Default" button: restores standard CEFR mapping

30.2 Functional Requirements

ID	Requirement
LEVEL-01	Level mappings are loaded from GET /api/entity/:entityId/level-mapping.
LEVEL-02	When a student's placement results are displayed, both the CEFR level and the entity's internal level name are shown side by side.
LEVEL-03	Level mappings must not have overlapping score ranges. Frontend validates this before saving.

---

33. White-Label Branding Settings

Route: /admin/entity/:entityId/branding Access: Authenticated, role = admin or mastercorporate

31.1 Page Layout

Branding configuration form:

Field	Type	Notes
Entity Logo	Image upload	Accepted formats: PNG, SVG, JPEG. Max 2MB. Displayed in header and login page.
Primary Color	Colour picker	Used for buttons, links, active states
Secondary Color	Colour picker	Used for accents, badges, secondary buttons
Background Color	Colour picker	Used for page backgrounds
Custom Subdomain	Text input	e.g., "utas" results in "utas.encoach.com"
Login Page Title	Text input	Custom welcome message on the login page
Login Page Description	Textarea	Custom description text
Favicon	Image upload	32x32 or 64x64 ICO/PNG

• Live Preview panel on the right showing how the login page and dashboard will look with the configured branding
• "Save Branding" button: PUT /api/entity/:entityId/branding
• "Reset to Default" button: restores EnCoach default branding

31.2 Functional Requirements

ID	Requirement
BRAND-01	When a student linked to an entity logs in, the frontend loads entity branding from GET /api/entity/branding (using the authenticated user's entity_id).
BRAND-02	Branding is applied via CSS custom properties: --primary, --secondary, --background. These override the default Tailwind theme.
BRAND-03	The logo replaces the EnCoach logo in the header, login page, and PDF reports.
BRAND-04	White-labelling affects ONLY the presentation layer. No workflow logic changes.
BRAND-05	If no entity branding is configured (or student has no entity), the default EnCoach branding is used.

---

Part XI -- Math and IT Subject Support

34. Math Content Rendering

32.1 Formula Display

All math content must be rendered using KaTeX (preferred for performance) or MathJax as fallback:

• Inline formulas: $x^2 + y^2 = z^2$ rendered inline with text
• Block formulas: $$\int_0^1 x^2 dx = \frac{1}{3}$$ rendered as centered blocks
• Formula rendering must work in: questions, answer options, passage text, explanations, and feedback

32.2 Math Question Types

In addition to the standard question types (MCQ, gap fill, TF/NG), Math requires:

Question Type	Renderer	Example
Numerical Input	Number input with tolerance	"Solve: 2x + 5 = 13. x = ___" (accept 4 +/- 0.01)
Expression Input	Math input field (using mathquill or similar)	"Simplify: \frac{2x^2}{4x} = ___"
Graph Plot	Interactive graph component	"Plot the function $y = 2x + 3$"
Multiple Steps	Step-by-step input fields	"Show your working:" followed by numbered step inputs
Matrix Input	Grid of number inputs	"Enter the result matrix:"

32.3 Dependencies

npm install katex react-katex

---

35. IT Content Rendering

33.1 Code Display and Execution

IT course content requires code display and optionally code execution:

Component	Implementation	Notes
Code Block	Syntax-highlighted code viewer (using prism-react-renderer or highlight.js)	Supports: Python, JavaScript, HTML, CSS, SQL, Java, C
Code Editor	Monaco Editor (VS Code's editor) or CodeMirror	For IT exercises where students write code
Code Output	Terminal-like output display	Shows stdout/stderr from code execution

33.2 IT Question Types

Question Type	Renderer	Example
Code Completion	Code editor with blanks	"Complete the function: def add(a, b): return ___"
Code Output Prediction	Code block + MCQ	"What does this code output?"
SQL Query	SQL editor + result table display	"Write a query to select all users older than 30"
Drag-and-Drop Code	Draggable code blocks	"Arrange these lines in the correct order"
Networking Diagram	Interactive network diagram component	"Identify the subnet for this IP address"

33.3 Dependencies

npm install @monaco-editor/react prism-react-renderer

---

36. Subject-Agnostic Placement and Courses

34.1 Subject Selector Component

A reusable component that appears at the start of placement tests and course generation for students with Math or IT goals. The selector shows available subjects with icons:

• English (default)
• Mathematics (when available, September 2026)
• Information Technology (when available, September 2026)

34.2 Taxonomy Browser

Route: /admin/taxonomy

Tree view of the subject taxonomy:

Subject: Mathematics
  └── Domain: Algebra
       ├── Topic: Linear Equations
       │     ├── Learning Objective: Solve single-variable linear equations
       │     └── Learning Objective: Graph linear equations
       └── Topic: Quadratic Equations
             ├── Learning Objective: Factor quadratic expressions
             └── Learning Objective: Apply the quadratic formula

Admin can CRUD taxonomy nodes. The taxonomy drives what content the AI generates and how the adaptive engine organises modules.

34.3 Functional Requirements

ID	Requirement
SUBJ-01	The subject selector fetches available subjects from GET /api/taxonomy/subjects.
SUBJ-02	Placement test dimensions change per subject (Grammar/Vocab/Reading/Speaking for English, Arithmetic/Algebra/Geometry/Problem-Solving for Math, etc.). The test briefing page (Section 7) dynamically adjusts.
SUBJ-03	Course generation and AI content generation use the same pipelines regardless of subject. The subject taxonomy determines the content topics.

---

Part XII -- Score Release and Reporting

37. Admin Score Approval Queue

Route: /admin/scores/pending Access: Authenticated, role = admin or corporate or mastercorporate

35.1 Page Layout

Table of exam results pending approval:

Column	Content
Student Name	Text
Exam Title	Text
Exam Type	Official / Practice
Submitted At	Timestamp
Overall Score	Band or CEFR
Status	"Pending Approval" / "Approved" / "Rejected"
Action	"Approve" / "Reject" / "View Details" buttons

Bulk actions: "Approve All Selected"

35.2 Functional Requirements

ID	Requirement
SCORE-01	Only exams with results_release_mode = manual_approval appear in this queue.
SCORE-02	"Approve" calls POST /api/scores/:attemptId/release. The student is notified and can now see their results.
SCORE-03	"Reject" opens a dialog for a reason. Calls POST /api/scores/:attemptId/reject with reason text. The student sees: "Your results require further review. Reason: [reason]."
SCORE-04	Practice exams (results_release_mode = auto) never appear in this queue. Their results are auto-released.

---

38. PDF Report with QR Code

36.1 Report Content

The PDF report is generated on the backend but the frontend triggers it and provides a download link.

Report contents:

• Header: Entity logo (if white-labelled) or EnCoach logo, report title ("Exam Results Report")
• Student info: Name, email, student ID, entity name (if applicable)
• Exam info: Title, type, date taken, exam ID
• Scores: Per-skill band scores and overall band score, CEFR equivalent
• Performance summary: Strengths and weaknesses, per-question accuracy by category
• QR Code: Embedded at bottom-right. Encodes: student_id, exam_id, score, issue_date, and a verification_hash. When scanned, links to the public verification page.
• Footer: "Verified by EnCoach Platform. Scan QR code to verify authenticity."

36.2 Frontend Integration

• "Download PDF Report" button on the results page (Section 17) calls GET /api/reports/exam/:attemptId/pdf and triggers a browser download.
• Loading state: "Generating your report..." spinner while the backend creates the PDF.

---

39. Public Score Verification Page

Route: /verify/:verificationHash Access: Public (no authentication required)

37.1 Page Layout

Minimal public page with EnCoach branding:

• Header: "Score Verification"
• Verification result:
  • If valid: Green checkmark. "This result is verified." Student name, exam type, overall score, date issued.
  • If invalid: Red X. "This verification code is invalid or has expired."
• No other navigation or links (this is a public verification page only)

37.2 Functional Requirements

ID	Requirement
VERIFY-QR-01	The page calls GET /api/verify/:hash on mount. Returns verification status and basic score info (no detailed per-question data).
VERIFY-QR-02	This page must be accessible without authentication.
VERIFY-QR-03	The verification hash is a signed token that cannot be tampered with.

---

Part XIII -- Technical Specifications

40. New Pages Inventory

#	Page	Route	Role	Section
1	Registration (enhanced)	/register	Public	4
2	Email Verification	/verify-email	Public	5
3	Onboarding Wizard	/onboarding	Student	6
4	Placement Briefing	/student/placement	Student	7
5	CAT Test Interface	/student/placement/test	Student	8
6	Placement Results	/student/placement/results	Student	9
7	Payment/Access	/student/placement/access	Student	10
8	Template Selection	/admin/exam/create	Admin/Teacher	11
9	IELTS Exam Create	/admin/exam/ielts/create	Admin/Teacher	12
10	IELTS Skill Config	/admin/exam/ielts/:id/skills	Admin/Teacher	13
11	Content Pool Browser	/admin/exam/ielts/:id/content	Admin/Teacher	14
12	Exam Validation	/admin/exam/ielts/:id/validate	Admin/Teacher	15
13	Custom Exam Create	/admin/exam/custom/create	Admin/Teacher	16
14	Exam Session	/student/exam/:id/session	Student	17
15	Grading Queue	/admin/exam/:id/grading	Admin/Teacher	18
16	Exam Results	/student/exam/:id/results	Student	19
17	Gap Analysis	/student/course/generate	Student/Admin	21
18	Course Configure	/admin/course/configure/:id	Admin/Teacher	22
19	Module Builder	/admin/course/:id/modules	Admin/Teacher	23
20	Course Delivery	/student/course/:id	Student	24
21	Teacher Progress	/teacher/course/:id/progress	Teacher	24
22	Bulk Upload	/admin/entity/students/upload	Admin	25
23	Credential Dashboard	/admin/entity/students/credentials	Admin	26
24	First Login Reset	/reset-password	Student	27
25	AI English Course	/student/course/ai-english/:id	Student	28
26	AI English Quality	/admin/ai-course/english/:id/quality	Admin/Teacher	28
27	AI English Taxonomy	/admin/ai-course/english/taxonomy	Admin	28
28	AI IELTS Course	/student/course/ai-ielts/:id	Student	29
29	AI IELTS Validation	/admin/ai-course/ielts/:id/validation	Admin	29
30	Adaptive Dashboard	/admin/adaptive/dashboard	Admin	30
31	Adaptive Student Detail	/admin/adaptive/student/:id	Admin/Teacher	31
32	Adaptive Settings	/teacher/adaptive/settings	Teacher	30
33	Level Mapping Config	/admin/entity/:id/level-mapping	Admin	32
34	White-Label Branding	/admin/entity/:id/branding	Admin	33
35	Taxonomy Browser	/admin/taxonomy	Admin	36
36	Score Approval Queue	/admin/scores/pending	Admin	37
37	Score Verification	/verify/:hash	Public	39

Total new pages: 37

---

41. New Services Inventory

#	Service File	Purpose	Key Endpoints
1	signup.service.ts	Registration, OTP, onboarding	/api/auth/register, /api/auth/verify-email, /api/auth/resend-otp, /api/auth/check-email, /api/onboarding/*
2	placement.service.ts	CAT placement test	/api/placement/start, /api/placement/answer, /api/placement/autosave, /api/placement/results, /api/placement/speaking-upload, /api/placement/speaking-status, /api/placement/learning-path
3	exam-template.service.ts	Template selection, custom templates	/api/exam/templates, /api/exam/templates/custom
4	ielts-exam.service.ts	IELTS exam CRUD and assembly	/api/exam/ielts/create, /api/exam/ielts/:id/* (skills, content-pool, auto-assemble, suggest, validate, assign)
5	custom-exam.service.ts	Custom exam CRUD	/api/exam/custom/create, /api/exam/custom/:id/*
6	exam-session.service.ts	Student exam taking	/api/exam/:id/session, /api/exam/:id/autosave, /api/exam/:id/submit
7	grading.service.ts	Manual and AI grading	/api/grading/queue, /api/grading/:id/submit, /api/grading/ai-suggest
8	course-generation.service.ts	Gap analysis, course config	/api/course/gap-analysis, /api/course/auto-generate, /api/course/create, /api/course/:id/*
9	ai-course.service.ts	AI course generation (English + IELTS)	/api/ai-course/english/create, /api/ai-course/ielts/create, /api/ai-course/:id/quality, /api/ai-course/:id/validation
10	entity-onboarding.service.ts	Bulk upload, credentials	/api/entity/students/validate-csv, /api/entity/students/bulk-create, /api/entity/students/send-credentials, /api/entity/students/sis-import
11	adaptive.service.ts	Adaptive engine UI	/api/adaptive/dashboard, /api/adaptive/students, /api/adaptive/settings, /api/adaptive/student/:id/signals
12	level-mapping.service.ts	Entity level mapping	/api/entity/:id/level-mapping
13	branding.service.ts	White-label branding	/api/entity/:id/branding, /api/entity/branding
14	score-release.service.ts	Score approval	/api/scores/pending, /api/scores/:id/release, /api/scores/:id/reject
15	report.service.ts	PDF report generation	/api/reports/exam/:id/pdf
16	verification.service.ts	Public score verification	/api/verify/:hash
17	taxonomy.service.ts	Subject taxonomy CRUD	/api/taxonomy/subjects, /api/taxonomy/tree

Total new services: 17

---

42. New Types Inventory

#	Type File	Key Interfaces
1	signup.ts	RegisterRequest, VerifyEmailRequest, OnboardingData, Goal
2	placement.ts	CATSession, CATQuestion, CATAnswer, PlacementResult, LearningPathPreview, SpeakingUpload
3	exam-template.ts	ExamTemplate, TemplatePath, TemplateCard, TemplateType
4	ielts-exam.ts	IELTSExamConfig, IELTSSkillConfig, ContentPoolItem, AssemblyMode, ExamValidationReport
5	custom-exam.ts	CustomExamConfig, CustomSection, CustomScoringMethod, CustomExamCreateRequest
6	exam-session.ts	ExamSession, ExamSection, ExamQuestion, ExamAnswer, SubmissionSummary
7	grading.ts	GradingQueueItem, RubricCriteria, AIGradeSuggestion, GradeSubmission
8	course-generation.ts	GapAnalysis, SkillGap, CourseConfig, ModuleConfig, ProgressionModel
9	ai-course.ts	AICourseConfig, QualityGateResult, IELTSValidationResult, ExaminerReview
10	entity-onboarding.ts	CSVValidationReport, BulkCreateResult, CredentialStatus, EntityStudent
11	adaptive.ts	AdaptiveDashboard, AdaptiveStudentProfile, EngineSignal, EngineDecision, ThresholdSettings, AbilityModel
12	level-mapping.ts	LevelMapping, LevelMappingRow
13	branding.ts	EntityBranding, BrandingConfig
14	score-release.ts	PendingScore, ScoreReleaseAction
15	math.ts	NumericalQuestion, ExpressionQuestion, MatrixQuestion, GraphQuestion
16	it.ts	CodeQuestion, SQLQuestion, CodeExecutionResult

Total new type files: 16

---

43. API Contracts

43.1 Authentication

All API calls (except public routes) require a JWT token in the Authorization header:

Authorization: Bearer <jwt_token>

Public routes (no auth required):

• POST /api/auth/register
• POST /api/auth/verify-email
• POST /api/auth/resend-otp
• POST /api/auth/check-email
• GET /api/verify/:hash

43.2 Standard Response Format

All API responses follow this envelope:

{
  "success": true,
  "data": { ... },
  "message": "optional message",
  "errors": []
}

Error responses:

{
  "success": false,
  "data": null,
  "message": "Error description",
  "errors": [
    { "field": "email", "message": "Email already exists" }
  ]
}

43.3 Pagination

List endpoints support pagination:

GET /api/resource?page=1&limit=20&sort=created_at&order=desc

Response includes:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 247,
    "total_pages": 13
  }
}

43.4 Full Endpoint Summary

Category	Endpoint Count	Section Reference
Auth & Signup	5	4--6
Placement Test	7	7--10
Exam Templates	3	11
IELTS Exam Config	12	12--15
Custom Exam Config	4	16
Exam Session	4	17
Grading	4	18
Course Generation	8	21--24
AI Course Generation	6	28--29
Entity Onboarding	6	25--27
Adaptive Engine	5	30--31
Entity/Branding	4	32--33
Score Release	4	37
Reports	1	38
Verification	1	39
Taxonomy	2	36
Total	~76

---

End of Document

Document Version: 1.1 Total New Pages: 37 Total New Services: 17 Total New Type Files: 16 Total New API Endpoints: ~76 Workflow Coverage: All 6 workflows + Exam Template Paths (International + Custom) + Adaptive Engine (4 phases) + Math/IT + White-Labelling + Score Release

This document covers the complete frontend implementation required by encoach_workflows_v3.pdf. The developer should implement these features on top of the existing 93-page frontend codebase.