Files

Talal Sharabi 68001d33e8 EnCoach Frontend v1 - Production-ready with full API integration

- 59 pages (52 original + 7 new adaptive learning pages)
- 14 AI components wired to real backend endpoints
- Real JWT authentication with 7 user roles
- 21 API service modules with TanStack Query hooks
- 14 TypeScript type definition files
- Entity-scoped permission system
- Universal adaptive learning engine pages (subjects, diagnostic, proficiency, learning plan, topic)
- Admin taxonomy and resource management pages
- All mock data removed, all pages connected to Odoo 19 REST API

docs/ contains:
- ENCOACH_UNIFIED_SRS.md (master product SRS)
- ODOO_BACKEND_SRS_v3.md (backend developer handoff)
- ENCOACH_PRODUCT_DESCRIPTION.md (stakeholder document)
- UTAS_MASTER_PLAN.md (project timeline)
- Supporting architecture and analysis documents

Made-with: Cursor

2026-03-25 22:52:04 +04:00

60 KiB

Raw Blame History

EnCoach Unified Platform -- Software Requirements Specification

Document Version: 1.0 Date: March 24, 2026 Status: Draft -- Architect Review Supersedes: ielts-ui/SRS-EnCoach.md (v2.0), MATH_IT_ADAPTIVE_LEARNING_SRS.md (v1.0) Author: EnCoach Engineering Team

Part I -- Platform Foundation

Introduction
System Architecture
User Roles and Multi-Tenancy
Authentication and Authorization
Global UI Shell

Part II -- Universal Subject Engine 6. Subject Taxonomy 7. Diagnostic Assessment 8. Proficiency Profile 9. Learning Plan Generation 10. Hybrid Content Delivery 11. Progress Tracking and Mastery

Part III -- LMS Module 12. Course Management 13. Batch and Enrollment 14. Timetable and Attendance 15. Gradebook and Reports

Part IV -- Exam Engine 16. Exam Management 17. AI Content Generation 18. Exam Delivery 19. AI Grading

Part V -- AI Services 20. AI Services Catalog 21. AI Integration in Frontend

Part VI -- Administration 22. User Management 23. Entity Management 24. Classroom Management 25. Assignment Management 26. Permission Management

Part VII -- Support and Commercial 27. Ticketing System 28. Subscriptions and Payments 29. Training Content

Part VIII -- Technical Specifications 30. Data Models 31. REST API Specification 32. Frontend Page Inventory 33. Non-Functional Requirements

Part I -- Platform Foundation

1. Introduction

1.1 Purpose

This document is the definitive SRS for the EnCoach platform rebuild. It specifies all functional and non-functional requirements for a unified AI-powered education platform that serves:

UTAS students (institutional, SIS-synced, curriculum-aligned learning paths)
Freelance students (self-registered, AI-generated learning plans, subscription-based)

The platform supports multiple subjects (IELTS/English, Mathematics, Information Technology, and future subjects) through a universal adaptive learning engine.

1.2 Scope

In scope:

All production features from the existing EnCoach platform (behavioural parity)
Universal adaptive learning engine (diagnostic, proficiency, learning plans, mastery)
Multi-subject support (IELTS, Math, IT -- extensible to any subject)
LMS module (OpenEduCat-backed courses, batches, timetable, attendance)
Multi-tenant operation (UTAS institutional + freelance self-service)
AI services integration (GPT-4o, Whisper, Polly, ELAI, GPTZero, FAISS)
New React frontend with real AI integration (replacing simulated components)
Odoo 19 backend with REST API

Out of scope:

Mobile native applications (iOS/Android)
Pixel-perfect recreation of old UI (new UI/UX takes precedence)
Database internals beyond Odoo model specifications
Hosting SLAs and legal/commercial terms

1.3 Definitions

Term	Definition
Subject	Top-level academic discipline (IELTS/English, Mathematics, IT). Subjects are the root of the taxonomy.
Domain	Major area within a subject (e.g., Algebra, Networking, Writing).
Topic	Specific teachable unit within a domain (e.g., Linear Equations, TCP/IP).
Learning Objective	Measurable skill a student should gain from a topic.
Entity	Tenant/organization with licenses, roles, and scoped permissions. UTAS is an entity.
Classroom	User group with an admin and participants, scoped to an entity.
Assignment	Scheduled set of exams for assignees; deep link `/exam?assignment={id}`.
Skill Module	Legacy term for IELTS skill areas (reading, listening, writing, speaking, level). In the new system, skill modules are topics within the English subject.
Mastery Level	Numeric score (0-100) indicating proficiency on a topic.
Learning Plan	AI-generated, sequenced list of topics for a student to study.
Resource	Human-uploaded learning material (PDF, video, link) tagged to topics.
UTAS Student	Student enrolled through UTAS SIS sync, following institutional curriculum.
Freelance Student	Self-registered student with AI-generated learning plans, individual subscription.

1.4 Key Architectural Decisions

#	Decision	Rationale
AD-1	Universal Subject Engine replaces hardcoded IELTS	The exam module's `MODULE_SELECTION` becomes dynamic, driven by subject taxonomy. "Reading, Listening, Writing, Speaking" become skill types within the English subject, not hardcoded platform concepts. This allows Math, IT, and future subjects to use the same engine.
AD-2	Two student modes	UTAS students follow curriculum + adaptive learning with SIS sync. Freelance students get fully AI-generated learning plans with no curriculum dependency. Both share the same platform.
AD-3	AI components become real	Each of the 15 simulated AI components in the new frontend maps to specific backend AI services. No simulation in production.
AD-4	OpenEduCat as LMS backbone	Course, batch, timetable, and attendance models come from OpenEduCat Odoo modules. A REST API bridge exposes them to the React frontend.
AD-5	Permission model extended for multi-subject	Current hardcoded permissions (`generate_reading`, `view_writing`, etc.) are replaced with subject-parameterized permissions (`generate_exam:{subject}`, `view_exam:{subject}`).

2. System Architecture

2.1 Architecture Overview

graph TB
    subgraph clients ["Client Layer"]
        Browser["React 18 SPA<br/>Vite + TypeScript + shadcn/ui<br/>50+ pages"]
    end

    subgraph gateway ["API Gateway"]
        Nginx["Nginx<br/>SSL Termination<br/>Route Proxy"]
    end

    subgraph backend ["Backend -- Odoo 19"]
        API["REST API Controllers"]
        Core["Core Modules<br/>Users, Entities, Roles"]
        Adaptive["Adaptive Engine<br/>Taxonomy, Diagnostic,<br/>Proficiency, Learning Plans"]
        Exam["Exam Engine<br/>Universal multi-subject"]
        LMS["OpenEduCat LMS<br/>Courses, Batches,<br/>Timetable, Attendance"]
        AImod["AI Modules<br/>Generation, Grading,<br/>Media, Coaching"]
        Biz["Business Modules<br/>Subscriptions, Tickets,<br/>Registration, Assignments"]
    end

    subgraph ai ["AI Services"]
        GPT["OpenAI GPT-4o"]
        Whisper["Whisper STT<br/>(local)"]
        Polly["AWS Polly TTS"]
        ELAI_svc["ELAI Avatars"]
        GPTZero_svc["GPTZero"]
        FAISS_svc["FAISS + SentenceTransformers"]
    end

    subgraph data ["Data"]
        PG["PostgreSQL 16"]
    end

    subgraph external ["External"]
        SIS["UTAS SIS"]
        Stripe_svc["Stripe"]
        PayPal_svc["PayPal"]
        Paymob_svc["Paymob"]
    end

    Browser -->|HTTPS| Nginx
    Nginx -->|"/app/*"| Browser
    Nginx -->|"/api/*"| API
    API --> Core
    API --> Adaptive
    API --> Exam
    API --> LMS
    API --> AImod
    API --> Biz
    AImod --> GPT
    AImod --> Whisper
    AImod --> Polly
    AImod --> ELAI_svc
    AImod --> GPTZero_svc
    AImod --> FAISS_svc
    Core --> PG
    Adaptive --> PG
    Exam --> PG
    LMS --> PG
    Biz --> PG
    API <-->|"REST sync"| SIS
    Biz --> Stripe_svc
    Biz --> PayPal_svc
    Biz --> Paymob_svc

2.2 Technology Stack

Layer	Technology
Frontend	React 18, TypeScript, Vite 5, React Router v6, TanStack Query
UI	shadcn/ui (Radix primitives), Tailwind CSS 3, Recharts, Lucide icons
Forms	react-hook-form + Zod validation
Backend	Odoo 19, Python 3.11
Database	PostgreSQL 16
LMS	OpenEduCat (Odoo-native modules)
AI	OpenAI GPT-4o/3.5-turbo, Whisper (local base model), AWS Polly Neural, ELAI, GPTZero, FAISS + all-MiniLM-L6-v2
Deployment	Docker Compose, Nginx reverse proxy
Version Control	Gitea

2.3 Multi-Tenant Model

graph TB
    subgraph tenants ["Tenant Types"]
        UTAS["UTAS Entity<br/>Institutional license<br/>SIS-synced students<br/>Curriculum-bound"]
        Freelance["Freelance<br/>No entity / self-entity<br/>Self-registered<br/>AI-generated plans<br/>Individual subscription"]
        Corp["Corporate Entities<br/>Bulk licenses<br/>Managed enrollment"]
    end

    subgraph shared ["Shared Platform"]
        SubjectEngine["Universal Subject Engine"]
        ExamEngine["Exam Engine"]
        AIServices["AI Services"]
        LMSmod["LMS Module"]
    end

    UTAS --> SubjectEngine
    Freelance --> SubjectEngine
    Corp --> SubjectEngine
    SubjectEngine --> ExamEngine
    SubjectEngine --> AIServices
    SubjectEngine --> LMSmod

Mode	Registration	Learning Plan	Content	Billing
UTAS Student	SIS sync or admin batch import	AI-generated, curriculum-aligned (topics from UTAS syllabus)	Manual resources from UTAS staff + AI supplementary	Institutional license
Freelance Student	Self-registration	Fully AI-generated (topic selection from global taxonomy)	AI-generated primary + curated community resources	Individual subscription (Stripe/PayPal/Paymob)
Corporate Student	Admin batch import or code-based	Teacher/admin assigned + adaptive	Entity-managed resources + AI supplementary	Corporate license

3. User Roles and Multi-Tenancy

3.1 User Types

Type	Access	Key Capabilities
`student`	Student portal	Take exams, follow learning plans, view grades, attend classes, receive AI coaching
`teacher`	Teacher portal	Create courses, manage assignments, grade students, upload resources, view class analytics
`admin`	Full admin portal	Manage users/entities/classrooms, configure platform, generate exams, manage workflows
`corporate`	Corporate dashboard	Manage entity members, view entity statistics, bulk operations
`mastercorporate`	Multi-entity corporate	Cross-entity management and reporting
`agent`	Sales agent	Visible on landing page, sales operations
`developer`	Developer tools	System diagnostics, advanced configuration

3.2 Entity-Scoped Permissions

All data access is scoped by entity membership. A user may belong to multiple entities with different roles in each. Permission checks combine global user type + entity role permissions.

4. Authentication and Authorization

4.1 Authentication

Method	Detail
Primary	Odoo JWT (HS256). Login returns access token; all API calls include `Authorization: Bearer <token>`.
Session	Token stored in httpOnly cookie or localStorage (frontend decision).
Registration	Self-registration (freelance), batch import (institutional), code-based (corporate).
Password Reset	Email-based verification flow via `/api/reset` and `/api/reset/sendVerification`.

4.2 Authorization -- Entity Role Permissions

77 entity-scoped permissions organized by category:

Category	Permissions
User Management	`view_students`, `edit_students`, `delete_students`, `view_teachers`, `edit_teachers`, `delete_teachers`, `view_corporates`, `edit_corporates`, `delete_corporates`, `view_mastercorporates`, `edit_mastercorporates`, `delete_mastercorporates`, `create_user`, `create_user_batch`
Exam Management	`generate_{module}`, `view_{module}`, `delete_{module}` for each subject skill. Legacy: reading/listening/writing/speaking/level. New: parameterized by subject and skill via subject taxonomy.
Classroom	`view_classrooms`, `create_classroom`, `rename_classrooms`, `add_to_classroom`, `remove_from_classroom`, `delete_classroom`, `upload_classroom`
Entity	`view_entities`, `rename_entity`, `add_to_entity`, `remove_from_entity`, `delete_entity`, `view_entity_roles`, `create_entity_role`, `rename_entity_role`, `edit_role_permissions`, `assign_to_role`, `delete_entity_role`, `view_entity_statistics`
Assignment	`view_assignments`, `create_assignment`, `edit_assignment`, `delete_assignment`, `start_assignment`, `archive_assignment`
Content	`create_code`, `create_code_batch`, `view_code_list`, `delete_code`, `edit_grading_system`
Reporting	`view_statistics`, `download_statistics_report`, `view_student_performance`, `view_student_record`, `download_student_record`, `download_user_list`
Financial	`pay_entity`, `view_payment_record`
Workflow	`view_workflows`, `configure_workflows`, `edit_workflow`, `delete_workflow`, `view_approval_workflows`, `update_exam_privacy`, `view_confidential_exams`, `create_confidential_exams`, `create_public_exams`

4.3 Global Permissions

Global permissions control page-level access independent of entity:

Topic	Permissions
Manage Corporate	`viewCorporate`, `editCorporate`, `deleteCorporate`, `createCodeCorporate`
Manage Admin	`viewAdmin`, `editAdmin`, `deleteAdmin`, `createCodeAdmin`
Manage Student	`viewStudent`, `editStudent`, `deleteStudent`, `createCodeStudent`
Manage Teacher	`viewTeacher`, `editTeacher`, `deleteTeacher`, `createCodeTeacher`
Manage Exams	`createReadingExam`, `createListeningExam`, `createWritingExam`, `createSpeakingExam`, `createLevelExam` -- extended per subject
View Pages	`viewExams`, `viewExercises`, `viewRecords`, `viewStats`, `viewTickets`, `viewPaymentRecords`
Manage Groups	`viewGroup`, `editGroup`, `deleteGroup`, `createGroup`
Manage Codes	`viewCodes`, `deleteCodes`, `createCodes`
Super	`all`

4.4 Permission Extension for Multi-Subject (AD-5)

The current permission model is IELTS-hardcoded (generate_reading, createWritingExam, etc.). For multi-subject support:

Strategy: Add subject-parameterized permissions while maintaining backward compatibility.

Current (IELTS-only)	New (Universal)	Mapping
`generate_reading`	`generate_exam:english:reading`	Existing English exams auto-map
`generate_writing`	`generate_exam:english:writing`	Same
(new)	`generate_exam:math:algebra`	New subject permissions
(new)	`generate_exam:it:networking`	New subject permissions
(new)	`manage_taxonomy:{subject}`	Taxonomy administration per subject
(new)	`manage_resources:{subject}`	Resource upload per subject
(new)	`view_adaptive:{subject}`	View adaptive learning data per subject

5. Global UI Shell

ID	Requirement	Source
FR-GNAV-01	Brand/logo links to role-appropriate dashboard	Production
FR-GNAV-02	Student: subject progress indicators (mastery % per enrolled subject)	New (replaces IELTS-only skill indicators)
FR-GNAV-03	Help button opens ticket submission with page context	Production
FR-GNAV-04	Subscription/expiry indicator; link to payment when applicable	Production
FR-GNAV-05	Profile link to `/profile`	Production
FR-GNAV-06	Mobile-responsive menu	Production
FR-GNAV-07	AI Search Bar (global) -- keyword search with AI-powered suggestions, route to relevant pages	New frontend
FR-GNAV-08	AI Assistant Drawer -- chat-style AI help accessible from any page	New frontend

ID	Requirement
FR-SIDE-01	Entries appear only when permitted (user type + entity permissions)
FR-SIDE-02	Sidebar minimize preference persisted locally
FR-SIDE-03	Logout ends session and clears state
FR-SIDE-04	Ticket badge shows assigned count

Student sidebar: Dashboard, Subjects, Courses, Assignments, Grades, Attendance, Timetable, Profile

Teacher sidebar: Dashboard, Courses, Assignments, Attendance, Students, Timetable, Profile

Admin sidebar (grouped):

Group	Items
LMS	Dashboard, Courses, Students, Teachers, Batches, Timetable, Reports, Settings
Platform	Platform Dashboard
Academic	Assignments, Exams List, Exam Structures, Rubrics, Generation, Approval Workflows
Management	Users, Entities, Classrooms, Taxonomy Manager, Resource Manager
Reports	Student Performance, Stats Corporate, Record
Training	Vocabulary, Grammar
Support	Payment Record, Tickets, Settings

5.3 Breadcrumbs

Inner pages show: Home > Section > Nested segments (e.g., Assignments > Creator, Training > Vocabulary).

Part II -- Universal Subject Engine

6. Subject Taxonomy

6.1 Hierarchy

Subject (e.g., Mathematics)
└── Domain (e.g., Algebra)
    └── Topic (e.g., Linear Equations)
        └── Learning Objective (e.g., "Solve 2-variable systems")

Topics form a directed acyclic graph via prerequisite relationships. A student cannot begin a topic until all prerequisites reach Proficient (mastery >= 60%).

6.2 IELTS / English Taxonomy

The existing IELTS skills map into the universal taxonomy:

English / IELTS
├── Reading
│   ├── Skimming and Scanning (prerequisites: none)
│   ├── Detail Comprehension (prerequisites: Skimming)
│   ├── Inference and Deduction (prerequisites: Detail Comprehension)
│   └── Academic Reading (prerequisites: Inference)
├── Listening
│   ├── Section 1-2: Social/Everyday (prerequisites: none)
│   ├── Section 3-4: Academic (prerequisites: Section 1-2)
│   └── Note/Summary Completion (prerequisites: Section 1-2)
├── Writing
│   ├── Task 1 General: Letter (prerequisites: none)
│   ├── Task 1 Academic: Data Description (prerequisites: none)
│   └── Task 2: Essay (prerequisites: Task 1 General or Task 1 Academic)
├── Speaking
│   ├── Part 1: Introduction (prerequisites: none)
│   ├── Part 2: Long Turn (prerequisites: Part 1)
│   └── Part 3: Discussion (prerequisites: Part 2)
└── General English
    ├── Grammar Foundations (prerequisites: none)
    ├── Vocabulary Building (prerequisites: none)
    └── Pronunciation (prerequisites: none)

6.3 Mathematics Taxonomy

Mathematics
├── Arithmetic
│   ├── Number Operations (prerequisites: none)
│   ├── Fractions and Decimals (prerequisites: Number Operations)
│   └── Ratios and Proportions (prerequisites: Fractions)
├── Algebra
│   ├── Algebraic Expressions (prerequisites: Number Operations)
│   ├── Linear Equations (prerequisites: Algebraic Expressions)
│   ├── Quadratic Equations (prerequisites: Linear Equations)
│   └── Polynomials (prerequisites: Quadratic Equations)
├── Geometry
│   ├── Basic Shapes (prerequisites: Number Operations)
│   ├── Angles and Triangles (prerequisites: Basic Shapes)
│   ├── Coordinate Geometry (prerequisites: Linear Equations, Basic Shapes)
│   └── Trigonometry (prerequisites: Angles, Coordinate Geometry)
├── Statistics and Probability
│   ├── Data Representation (prerequisites: Number Operations)
│   ├── Central Tendency (prerequisites: Data Representation)
│   └── Basic Probability (prerequisites: Fractions)
└── Calculus
    ├── Limits (prerequisites: Polynomials, Coordinate Geometry)
    ├── Derivatives (prerequisites: Limits)
    └── Integrals (prerequisites: Derivatives)

6.4 Information Technology Taxonomy

Information Technology
├── Computer Fundamentals
│   ├── Hardware Components (prerequisites: none)
│   ├── Operating Systems (prerequisites: Hardware)
│   └── Number Systems (prerequisites: none)
├── Networking
│   ├── Network Basics (prerequisites: Hardware)
│   ├── TCP/IP Model (prerequisites: Network Basics)
│   ├── IP Addressing (prerequisites: TCP/IP, Number Systems)
│   └── Network Security (prerequisites: IP Addressing)
├── Databases
│   ├── Database Concepts (prerequisites: Operating Systems)
│   ├── SQL Fundamentals (prerequisites: Database Concepts)
│   ├── Database Design (prerequisites: SQL Fundamentals)
│   └── Advanced SQL (prerequisites: Database Design)
├── Programming
│   ├── Programming Logic (prerequisites: none)
│   ├── Python Basics (prerequisites: Programming Logic)
│   ├── Data Structures (prerequisites: Python Basics)
│   └── Object-Oriented Programming (prerequisites: Data Structures)
└── Cybersecurity
    ├── Security Fundamentals (prerequisites: Network Security)
    └── Cryptography Basics (prerequisites: Security Fundamentals, Number Systems)

6.5 Taxonomy Management

Action	Actor	API
Create/edit subjects	Admin	`POST/PATCH /api/subjects`
Create/edit domains	Admin / Staff	`POST/PATCH /api/domains`
Create/edit topics with prerequisites	Staff	`POST/PATCH /api/topics`
Create/edit learning objectives	Staff	Nested in topic API
Bulk import taxonomy (JSON/CSV)	Admin	`POST /api/subjects/{id}/taxonomy/import`
AI-suggest sub-topics for a domain	Staff	`POST /api/domains/{id}/ai-suggest`

7. Diagnostic Assessment

7.1 Purpose

When a student begins a new subject, a diagnostic assessment determines their per-topic proficiency. This is the input for learning plan generation. For English, this replaces/extends the existing Level Test.

7.2 Adaptive Algorithm

The diagnostic uses Computer Adaptive Testing: starts at medium difficulty, adjusts up on correct answers, down on incorrect. Cycles through domains round-robin.

Parameter	Default	Configurable
`questions_per_domain`	4	Yes (per subject)
`total_question_cap`	25	Yes
`time_limit_minutes`	45	Yes
`starting_difficulty`	`medium`	Yes
`mastery_per_correct`	+25	Yes
`mastery_per_incorrect`	-10	Yes

7.3 Question Types per Subject

Subject	Question Types
English	Multiple choice, fill blanks, short answer, essay (writing), oral (speaking)
Math	Multiple choice, numerical (tolerance-graded), short answer, fill blanks, worked problem (multi-step)
IT	Multiple choice, true/false, short answer, code completion, scenario-based

7.4 Integration with Existing Exam Model

Diagnostics reuse encoach.exam with is_diagnostic = True and a new subject_id field. MODULE_SELECTION extended with math_diagnostic, it_diagnostic. The existing level module maps to english_diagnostic.

8. Proficiency Profile

8.1 Mastery Levels

Level	Score Range	Color
Not Started	0-19%	Grey
Beginner	20-39%	Red
Developing	40-59%	Orange
Proficient	60-79%	Yellow
Mastered	80-100%	Green

8.2 Profile Updates

Trigger	Update Logic
Diagnostic	Initial scores set per topic
Practice exercises	+5 correct, -2 incorrect
Mastery quiz	Pass (>= threshold): topic mastered. Fail: weighted average recalculation.
Time decay	-5% per week of inactivity after 30 days, floor at last quiz score minus 20%

9. Learning Plan Generation

9.1 Two Modes

Mode	UTAS Student	Freelance Student
Scope	Topics from UTAS curriculum for enrolled courses	All topics in selected subject
Constraints	Semester dates, course schedule	Self-set target date or open-ended
Content	UTAS-uploaded resources + AI supplementary	AI-generated primary + community resources
Prerequisite enforcement	Yes, with teacher override	Yes, no override
Plan visibility	Student + assigned teacher + admin	Student only

9.2 Algorithm

Topological sort -- order topics respecting prerequisites
Filter mastered -- exclude topics with mastery >= threshold
Prioritize -- lowest mastery first, balanced across domains
Estimate duration -- based on topic complexity and current mastery
AI refinement -- GPT-4o generates motivational summary and specific advice

9.3 Plan Adjustments

Trigger	Action
Faster mastery than estimated	Unlock next topic early
3+ failed mastery quizzes	Additional resources, AI coaching intensified
Teacher override (UTAS)	Reorder, add/remove topics
7+ days inactive	Notification; 14+ days pauses plan

10. Hybrid Content Delivery

10.1 Content Resolution Order

Human-uploaded resources tagged to the topic (PDFs, videos, links)
AI-generated content if no human resources exist (explanations, worked examples, summaries)
Content gap flag if neither is available -- notifies admin

10.2 Resource Types

Type	Format	Upload
PDF	`.pdf`	File upload
Video	URL (YouTube, Vimeo) or file upload	URL or multipart
External Link	Any URL	URL field
Document	`.docx`, `.pptx`	File upload
Interactive	Embedded HTML	URL field

10.3 AI Coaching

Action	Backend Service	Trigger
Answer explanation	GPT-4o	After each practice question
Hint	GPT-4o	Student requests during practice
Study suggestion	GPT-4o	After completing a topic section
Weakness analysis	GPT-4o	After failing mastery quiz
Formula reference (Math)	Static + GPT-4o	On demand
Motivational nudge	GPT-4o	3+ days inactive

11. Progress Tracking and Mastery

11.1 Mastery Quiz

Parameter	Value
Questions	5-10 (configurable per subject)
Time limit	15 minutes (configurable)
Pass threshold	80% (configurable per subject)
Attempts	Unlimited, new questions each time
Cooldown	1 hour between attempts
On pass	Topic completed, next unlocked
On fail	Mastery recalculated, AI coaching triggered

11.2 Spaced Repetition

Days Since Mastery	Review
7	3 quick-recall questions
30	5 questions at original difficulty
90	Full mastery quiz equivalent

11.3 Analytics

Student: Overall mastery %, domain radar chart, plan progress, study streak, upcoming reviews.

Teacher: Class mastery heatmap, at-risk students, content gap report, time per topic vs estimate.

Admin: Subject-level stats (enrollments, completion rates, avg mastery), AI usage metrics, resource utilization.

Part III -- LMS Module

12. Course Management

12.1 Overview

Courses are managed through OpenEduCat models exposed via REST API. The frontend provides student, teacher, and admin course views.

12.2 Functional Requirements

ID	Requirement	Route	Role
FR-CRS-01	List enrolled courses with progress	`/student/courses`	Student
FR-CRS-02	View course detail with modules and lessons	`/student/courses/:id`	Student
FR-CRS-03	List managed courses	`/teacher/courses`	Teacher
FR-CRS-04	Create new course with modules and lessons	`/teacher/courses/new`	Teacher
FR-CRS-05	Edit existing course	`/teacher/courses/:id/edit`	Teacher
FR-CRS-06	Admin course management (all courses, all entities)	`/admin/courses`	Admin

12.3 Course Data Model

Field	Type	Description
title	String	Course title
code	String	Course code (e.g., "MATH101")
subject_id	Reference	Link to subject taxonomy
instructor_id	Reference	Assigned teacher
description	Text	Course description
level	Selection	Beginner, Intermediate, Advanced
modules	One2many	Course modules (units)
max_capacity	Integer	Enrollment limit
start_date / end_date	Date	Course period
status	Selection	draft, active, archived

13. Batch and Enrollment

ID	Requirement	Route
FR-BATCH-01	List batches with student counts	`/admin/batches`
FR-BATCH-02	View batch detail with enrolled students	`/admin/batches/:id`
FR-BATCH-03	Create batch, assign students and courses	Admin
FR-BATCH-04	Enrollment: student self-enrollment (freelance) or admin assignment (UTAS)	API

14. Timetable and Attendance

ID	Requirement	Route	Role
FR-TT-01	View personal timetable	`/student/timetable`	Student
FR-TT-02	View teaching timetable	`/teacher/timetable`	Teacher
FR-TT-03	Manage timetable (create, edit sessions)	`/admin/timetable`	Admin
FR-ATT-01	View personal attendance	`/student/attendance`	Student
FR-ATT-02	Record attendance for class	`/teacher/attendance`	Teacher

15. Gradebook and Reports

ID	Requirement	Route	Role
FR-GRD-01	View personal grades across courses	`/student/grades`	Student
FR-GRD-02	Grade student submissions	`/teacher/assignments/:id`	Teacher
FR-RPT-01	Academic reports with charts	`/admin/reports`	Admin
FR-RPT-02	AI-generated report narratives	`/admin/reports` (AiReportNarrative)	Admin

Part IV -- Exam Engine

16. Exam Management

16.1 Exam CRUD (Production Parity)

ID	Requirement	Source
FR-EX-01	Filter exams by module (extended: by subject and skill)	Production
FR-EX-02	Load exam by Exam ID	Production
FR-EX-03	Text search	Production
FR-EX-04	Pagination and page size	Production
FR-EX-05	Columns: title, creator, module, rubrics, difficulty, exercises, timer, access, created at	Production
FR-EX-06	Row actions: set public/private, edit, load, delete	Production
FR-EX-07	NEW: Subject filter (English, Math, IT) alongside module filter	New

16.2 Rubrics (Production Parity)

ID	Requirement
FR-RUB-01-05	Search, pagination, create rubric, filter dropdown, metadata and edit
FR-RG-01-05	Rubric groups: search, pagination, create, filter, edit/delete

16.3 Exam Structures (Production Parity)

ID	Requirement
FR-ES-01	Entity selector
FR-ES-02	Text search
FR-ES-03	Create structure (extended: per subject)
FR-ES-04	Delete structure(s)
FR-ES-05	Pagination

17. AI Content Generation

17.1 Generation per Subject

Subject	AI Generates	Prompt Model
English	Reading passages, listening scripts, writing tasks, speaking questions, level test exercises	GPT-4o (temp 0.7 for generation)
Math	Questions per topic (MCQ, numerical, word problems, worked problems)	GPT-4o with LaTeX output
IT	Questions per topic (MCQ, true/false, code completion, scenarios)	GPT-4o with code block output

17.2 Generation Workflow

ID	Requirement	Source
FR-GEN-01	Select title, label, entity, subject, and skill/module	Production (extended)
FR-GEN-02	AI generates exam content via GPT-4o	Production
FR-GEN-03	NEW: AI Creation Assistant -- modal flow for "Create with AI" for courses, exams, rubrics, assignments	New frontend (AiCreationAssistant)
FR-GEN-04	NEW: AI Generator Modal -- configurable generation parameters	New frontend (AiGeneratorModal)

18. Exam Delivery

18.1 Delivery Modes

Mode	Route	Chrome
Practice	`/exam`	Full UI with navigation
Assignment	`/exam?assignment={id}`	Reduced chrome
Official	`/official-exam`	Minimal chrome, strict timer
Diagnostic	`/student/diagnostic/:subjectId`	Adaptive, one question at a time
Mastery Quiz	`/student/mastery-quiz/:topicId`	Standard quiz, fresh questions

18.2 Media Integration

Media	Service	Usage
Listening audio	AWS Polly TTS	English listening sections (11 neural voices)
Speaking video	ELAI avatars	English speaking prompts (7 avatars)
Speaking transcription	Whisper STT	Student audio transcription for grading

19. AI Grading

19.1 Grading per Subject

Subject	Grading Type	Method
English Writing	Rubric-based (IELTS band scoring)	GPT-4o (temp 0.1) evaluates Task Achievement, Coherence, Lexical Resource, Grammar
English Speaking	Rubric-based (IELTS band scoring)	Whisper transcription + GPT-4o grading
English Short Answer	Passage-based	GPT-4o evaluates against correct answers
Math MCQ	Exact match	Direct comparison
Math Numerical	Tolerance-based	`abs(student - correct) <= tolerance`
Math Worked Problem	Step evaluation	GPT-4o evaluates methodology and answer
IT MCQ / True-False	Exact match	Direct comparison
IT Code Completion	AI evaluation	GPT-4o evaluates correctness, approach, quality
IT Scenario	AI evaluation	GPT-4o evaluates against rubric
All Writing	AI detection	GPTZero per-sentence analysis

19.2 Approval Workflows (Production Parity)

ID	Requirement
FR-AWF-01	List/filter workflows
FR-AWF-02	Create templates / add workflow
FR-AWF-03	NEW: AI Grading Assistant on workflow page

Part V -- AI Services

20. AI Services Catalog

Service	Model	Config	Usage
OpenAI GPT-4o	gpt-4o (primary), gpt-3.5-turbo (secondary)	Temp: 0.1 grading, 0.7 generation, 0.2 summaries. Max tokens: 4,097. JSON format.	Exam generation, grading, evaluation, training tips, learning plans, coaching, content generation
Whisper	base (local, ~1GB)	4 instances, round-robin, 16kHz mono, 30s chunks	Speaking transcription, audio-to-text
AWS Polly	Neural engine	11 voices, MP3, 3,000 char chunks	Listening exam audio
ELAI	7 avatars	ElevenLabs + Azure voices, fade_in animation	Speaking exam video, virtual tutoring
GPTZero	v2/predict/text	Per-sentence analysis, confidence scoring	Writing AI detection
FAISS	IndexFlatL2 + all-MiniLM-L6-v2	Top-5, per-subject indices	Training tips, content recommendations

21. AI Integration in Frontend

Each simulated AI component in the new frontend maps to a real backend service:

Frontend Component	Mock Behavior	Real Backend Integration
`AiAssistantDrawer`	Canned responses via `mockResponses` map	GPT-4o conversational API. Context: current page, student profile, recent activity. Endpoint: `POST /api/coach/chat`
`AiSearchBar`	Keyword-to-route mapping	GPT-4o semantic search + FAISS. Returns relevant content, pages, and actions. Endpoint: `POST /api/ai/search`
`AiCreationAssistant`	Simulated creation flows	GPT-4o generates course outlines, exam content, rubrics, assignments based on type parameter. Endpoints: existing `/api/exam/*/generate` + new `/api/courses/ai-generate`
`AiGeneratorModal`	Simulated with setTimeout	Real generation call to GPT-4o with progress streaming. Endpoint: existing generation endpoints
`AiGradingAssistant`	Fixed suggested marks	Real grading via `POST /api/evaluate/writing` or `/api/evaluate/speaking` or `/api/grading/multiple`. Returns scores + feedback
`AiWritingHelper`	`useAiSimulation` delay	GPT-4o writing assistance. Endpoint: `POST /api/coach/writing-help`
`AiGradeExplainer`	Static explanation	GPT-4o explains grade breakdown. Endpoint: `POST /api/coach/explain`
`AiStudyCoach`	Rotating static tips	Real adaptive engine: proficiency profile + FAISS tips + GPT-4o recommendations. Endpoint: `POST /api/coach/suggest`
`AiInsightsPanel`	Static insight cards	GPT-4o analysis of student/class data. Endpoint: `POST /api/ai/insights`
`AiTipBanner`	Static tips	Context-aware tips from FAISS + GPT-4o. Endpoint: `GET /api/coach/tip?context={page}`
`AiAlertBanner`	Static alerts	Rule-based alerts (attendance, grades) + GPT-4o severity assessment. Endpoint: `GET /api/ai/alerts`
`AiReportNarrative`	Static narrative	GPT-4o generates report narrative from analytics data. Endpoint: `POST /api/ai/report-narrative`
`AiRiskBadge`	Heuristic from mock data	Risk calculation from attendance + grades + engagement. Endpoint: included in student profile API
`AiBatchOptimizer`	Static suggestions	GPT-4o analyzes batch composition and suggests optimizations. Endpoint: `POST /api/ai/batch-optimize`
`useAiSimulation`	setTimeout + canned response	Replaced by real TanStack Query mutations to backend APIs

Part VI -- Administration

22. User Management (Production Parity)

ID	Requirement	Route
FR-USR-01	Filter by entity	`/users?type=student\|teacher\|corporate\|mastercorporate`
FR-USR-02	Text search (name/email)	Same
FR-USR-03	Download/export	Same
FR-USR-04	Pagination and page size	Same
FR-USR-05	Type-specific columns (name, email, type, entities, classrooms, student ID, verified)	Same
FR-USR-06	NEW: Subject enrollment status per student	New

23. Entity Management (Production Parity)

ID	Requirement
FR-ENT-01	Search and pagination
FR-ENT-02	Create entity (label, licenses/capacity, member selection)
FR-ENT-03	Cards: usage/capacity, role counts
FR-ENT-04	Role and permission management per entity

24. Classroom Management (Production Parity)

ID	Requirement
FR-CL-01	Entity filter and search
FR-CL-02	Cards: name, admin, entity, participant count
FR-CL-03	Create classroom
FR-CL-04	Transfer students across classrooms
FR-CL-05	Delete / bulk delete

25. Assignment Management (Production Parity)

ID	Requirement
FR-ASG-01	Tabs: Active, Planned, Past, Start Expired, Archived with counts
FR-ASG-02	Create assignment (entity, dates, classrooms, assignees, exams)
FR-ASG-03	Search and pagination (`state`, `page`, `size`)
FR-ASG-04	Breadcrumb navigation
FR-ASG-05	Assignment execution via `/exam?assignment={id}`
FR-ASG-06	NEW: Subject-scoped assignments (assign Math exams, IT exams, not just IELTS)

26. Permission Management (Production Parity + Extension)

ID	Requirement
FR-PERM-01	Navigate permission types at `/permissions`
FR-PERM-02	View/edit permission details at `/permissions/:id`
FR-PERM-03	NEW: Subject-parameterized permissions in UI (select subject, then skill permissions)

Part VII -- Support and Commercial

27. Ticketing System (Production Parity)

ID	Requirement
FR-TCK-01	Filters: Status, Type, Assignee, Source (All/Webpage/Platform)
FR-TCK-02	Sort by date
FR-TCK-03	Columns: ID, Type, Reporter, Source, Date, Subject, Status, Assignee, Corporate
FR-TCK-04	Pagination

28. Subscriptions and Payments

28.1 Billing Models

Model	Description	Payment
Institutional License	UTAS or corporate entity purchases bulk licenses	Invoice-based or Stripe/PayPal
Individual Subscription	Freelance student purchases access per subject or platform-wide	Stripe, PayPal, or Paymob
Package	Predefined bundles (e.g., "IELTS Complete", "Math + IT Bundle")	Per-package pricing

28.2 Functional Requirements (Production Parity)

ID	Requirement	Route
FR-PAY-01	Payment page with entity context	`/payment`
FR-PAY-02	Payment record / ledger	`/payment-record`
FR-PAY-03	Package listing	`/api/packages`
FR-PAY-04	Stripe checkout flow	`/api/stripe`
FR-PAY-05	PayPal checkout flow	`/api/paypal`
FR-PAY-06	Paymob checkout flow	`/api/paymob`
FR-PAY-07	Webhook handling (Stripe, PayPal, Paymob)	`/api/*/webhook`

29. Training Content

29.1 Existing (Production Parity)

ID	Requirement	Route
FR-TRN-01	Training hub with entity/user/time filters	`/training`
FR-TRN-02	Vocabulary training (progress, recommended, sections)	`/training/vocabulary`
FR-TRN-03	Grammar training (parallel structure)	`/training/grammar`
FR-TRN-04	Record view with entity/user/time/assignment filters	`/record`

29.2 New (Subject-Specific Tips)

ID	Requirement
FR-TRN-05	NEW: Math-specific training tips via FAISS (algebra, geometry, statistics indices)
FR-TRN-06	NEW: IT-specific training tips via FAISS (networking, databases, programming indices)
FR-TRN-07	NEW: Personalized post-exam tips using subject-specific FAISS + GPT-4o selection

Part VIII -- Technical Specifications

30. Data Models

30.1 Existing Models (from `ielts-be-v0`)

Model	Module	Purpose
`res.users` (extended)	`encoach_core`	User accounts with EnCoach fields
`encoach.entity`	`encoach_core`	Tenant organizations
`encoach.role`	`encoach_core`	Entity roles
`encoach.permission`	`encoach_core`	Role permissions
`encoach.code`	`encoach_core`	Registration codes
`encoach.invite`	`encoach_core`	User invitations
`encoach.exam`	`encoach_exam`	Exam definitions (extended with `subject_id`, `topic_ids`)
`encoach.approval.workflow`	`encoach_exam`	Exam approval workflows
`encoach.assignment`	`encoach_assignment`	Exam assignments
`encoach.group`	`encoach_classroom`	Classroom groups
`encoach.session`	`encoach_stats`	Exam session state
`encoach.stat`	`encoach_stats`	Per-exercise statistics (extended with `topic_id`, `subject_id`)
`encoach.evaluation`	`encoach_evaluation`	Writing/speaking evaluation results
`encoach.ai.job`	`encoach_evaluation`	Background AI job tracking
`encoach.training`	`encoach_training`	Training content records
`encoach.training.tip`	`encoach_training`	Training tips with FAISS embeddings
`encoach.walkthrough`	`encoach_training`	Module walkthroughs
`encoach.package`	`encoach_subscription`	Subscription packages
`encoach.subscription.payment`	`encoach_subscription`	Payment records
`encoach.discount`	`encoach_subscription`	Discount codes
`encoach.ticket`	`encoach_ticket`	Support tickets
`encoach.elai.avatar`	`encoach_ai_media`	ELAI avatar profiles
`encoach.registration`	`encoach_registration`	Batch registration mixin

30.2 New Models (Adaptive Learning Engine)

Model	Module	Purpose	Key Fields
`encoach.subject`	`encoach_taxonomy`	Top-level subjects	`name`, `code`, `is_active`, `diagnostic_config` (JSON), `mastery_threshold`, `grading_scale`, `grading_scale_config` (JSON)
`encoach.domain`	`encoach_taxonomy`	Subject domains	`name`, `code`, `subject_id`, `sequence`
`encoach.topic`	`encoach_taxonomy`	Topics with prerequisites	`name`, `code`, `domain_id`, `estimated_hours`, `difficulty_level`, `prerequisite_ids` (M2M self-ref), `question_type_weights` (JSON)
`encoach.learning.objective`	`encoach_taxonomy`	Measurable objectives	`name`, `topic_id`, `bloom_level`, `sequence`
`encoach.resource`	`encoach_resources`	Human-uploaded materials	`name`, `resource_type`, `file`/`url`, `topic_ids` (M2M), `author_id`, `is_published`, `review_status`
`encoach.proficiency`	`encoach_adaptive`	Per-student per-topic mastery	`student_id`, `topic_id`, `mastery` (float 0-100), `mastery_level`, `last_assessed`, `time_spent_minutes`
`encoach.learning.plan`	`encoach_adaptive`	Personalized study plan	`student_id`, `subject_id`, `status`, `ai_summary`, `overall_progress`, `target_completion`
`encoach.learning.plan.item`	`encoach_adaptive`	Plan items	`plan_id`, `topic_id`, `sequence`, `status` (locked/available/in_progress/completed), `estimated_hours`, `actual_hours`
`encoach.resource.completion`	`encoach_adaptive`	Resource viewing tracking	`student_id`, `resource_id`, `viewed`, `time_spent_minutes`, `rating`
`encoach.ai.content.cache`	`encoach_adaptive`	Cached AI-generated content	`topic_id`, `content_type`, `difficulty_level`, `content`, `model_used`, `review_status`

30.3 New Models (SIS Integration)

Model	Module	Purpose
`encoach.sis.sync`	`encoach_sis`	SIS sync job tracking
`encoach.sis.mapping`	`encoach_sis`	Field mapping between SIS and EnCoach

30.4 New Models (Branding)

Model	Module	Purpose
`encoach.branding`	`encoach_branding`	Tenant branding configuration (logo, colors, fonts)

31. REST API Specification

31.1 Existing Endpoints (81+)

All existing endpoints from the Odoo 19 backend remain. Key groups:

Group	Endpoints	Count
Auth	`/api/login`, `/api/logout`, `/api/reset`, `/api/reset/sendVerification`	4
Users	`/api/user`, `/api/users/update`, `/api/users/list`, `/api/users/{id}`	6
Entities & Roles	`/api/entities`, `/api/roles`, `/api/permissions`	7
Exams	`/api/exam`, `/api/exam/{module}`, `/api/exam/{module}/{id}`, `/api/exam/avatars`	7
AI Generation	`/api/exam/reading/`, `/api/exam/listening/`, `/api/exam/writing/`, `/api/exam/speaking/`, `/api/exam/level/*`	12
Media	`/api/exam/listening/media`, `/api/exam/speaking/media`, `/api/transcribe`	6
Evaluations	`/api/evaluate/writing`, `/api/evaluate/speaking`, `/api/grading/multiple`	6
Classrooms	`/api/groups`	3
Assignments	`/api/assignments`	8
Sessions & Stats	`/api/sessions`, `/api/stats`, `/api/statistical`	5
Training	`/api/training`, `/api/training/tips`, `/api/training/walkthrough`	4
Subscriptions	`/api/packages`, `/api/stripe`, `/api/paypal`, `/api/paymob` + webhooks	7
Registration	`/api/register`, `/api/code/{code}`, `/api/batch_users`	4
Tickets	`/api/tickets`	3
Storage	`/api/storage`	2
Approvals	`/api/approval-workflows`	3

31.2 New Endpoints (Adaptive Learning Engine, 40+)

Group	Method	Path	Description
Taxonomy	`GET`	`/api/subjects`	List subjects
	`GET`	`/api/subjects/{id}`	Get subject detail
	`POST`	`/api/subjects`	Create subject
	`PATCH`	`/api/subjects/{id}`	Update subject
	`DELETE`	`/api/subjects/{id}`	Delete subject
	`GET`	`/api/subjects/{id}/taxonomy`	Full taxonomy tree
	`POST`	`/api/subjects/{id}/taxonomy/import`	Bulk import
	`GET/POST/PATCH/DELETE`	`/api/domains`, `/api/topics`	Domain and topic CRUD
Resources	`GET`	`/api/resources`	List (filter by topic, type)
	`POST`	`/api/resources`	Upload resource (multipart)
	`PATCH`	`/api/resources/{id}`	Update metadata
	`DELETE`	`/api/resources/{id}`	Delete
	`GET`	`/api/resources/{id}/download`	Download file
	`POST`	`/api/resources/{id}/complete`	Mark viewed
	`POST`	`/api/resources/{id}/rate`	Rate (1-5)
Diagnostic	`POST`	`/api/diagnostic/start`	Start adaptive diagnostic
	`POST`	`/api/diagnostic/answer`	Submit answer, get next question
	`GET`	`/api/diagnostic/{id}/result`	Get diagnostic results
Proficiency	`GET`	`/api/proficiency`	Student's profile (by subject)
	`GET`	`/api/proficiency/summary`	Cross-subject summary
	`GET`	`/api/proficiency/class`	Class-level (teacher/admin)
Learning Plan	`GET`	`/api/learning-plan`	Active plan (by subject)
	`POST`	`/api/learning-plan/generate`	Generate/regenerate
	`PATCH`	`/api/learning-plan/{id}`	Teacher override
	`POST`	`/api/learning-plan/{id}/pause`	Pause plan
	`POST`	`/api/learning-plan/{id}/resume`	Resume plan
Content	`GET`	`/api/topics/{id}/content`	Get learning content (hybrid)
	`POST`	`/api/topics/{id}/generate-content`	Force AI generation
	`POST`	`/api/topics/{id}/practice`	Generate practice questions
	`POST`	`/api/topics/{id}/practice/grade`	Grade practice answers
	`POST`	`/api/topics/{id}/mastery-quiz`	Start mastery quiz
	`POST`	`/api/topics/{id}/mastery-quiz/submit`	Submit mastery quiz
AI Coaching	`POST`	`/api/coach/chat`	AI assistant conversation
	`POST`	`/api/coach/hint`	Request hint
	`POST`	`/api/coach/explain`	Request explanation
	`POST`	`/api/coach/suggest`	Study suggestions
	`POST`	`/api/coach/writing-help`	Writing assistance
	`GET`	`/api/coach/tip`	Contextual tip
AI Utilities	`POST`	`/api/ai/search`	Semantic search
	`POST`	`/api/ai/insights`	Data insights
	`GET`	`/api/ai/alerts`	Risk alerts
	`POST`	`/api/ai/report-narrative`	Report narrative
	`POST`	`/api/ai/batch-optimize`	Batch optimization
Analytics	`GET`	`/api/analytics/student`	Student analytics
	`GET`	`/api/analytics/class`	Class analytics
	`GET`	`/api/analytics/subject`	Subject analytics
	`GET`	`/api/analytics/content-gaps`	Content gap report

31.3 New Endpoints (LMS API Bridge)

Method	Path	Description
`GET/POST`	`/api/courses`	List/create courses
`GET/PATCH/DELETE`	`/api/courses/{id}`	Course CRUD
`POST`	`/api/courses/ai-generate`	AI-generate course outline
`GET/POST`	`/api/batches`	List/create batches
`GET/PATCH/DELETE`	`/api/batches/{id}`	Batch CRUD
`GET/POST`	`/api/timetable`	Timetable sessions
`GET/POST`	`/api/attendance`	Attendance records
`GET`	`/api/grades`	Gradebook

31.4 New Endpoints (SIS Integration)

Method	Path	Description
`POST`	`/api/sis/sync`	Trigger SIS sync
`GET`	`/api/sis/status`	Sync status
`GET`	`/api/sis/mappings`	Field mappings
`PATCH`	`/api/sis/mappings`	Update mappings

32. Frontend Page Inventory

32.1 Auth Pages (3)

Route	Page	API Dependencies
`/login`	Login	`POST /api/login`
`/register`	Register	`POST /api/register`
`/forgot-password`	Forgot Password	`POST /api/reset/sendVerification`

32.2 Student Pages (10+)

Route	Page	Key APIs	AI Components
`/student/dashboard`	Student Dashboard	`/api/user`, `/api/proficiency/summary`, `/api/learning-plan`	AiStudyCoach, AiTipBanner
`/student/subjects`	NEW: Subject Selection	`/api/subjects`, `/api/proficiency/summary`	--
`/student/diagnostic/:subjectId`	NEW: Diagnostic Test	`/api/diagnostic/start`, `/api/diagnostic/answer`	--
`/student/proficiency/:subjectId`	NEW: Proficiency Profile	`/api/proficiency?subjectId=`	--
`/student/plan/:subjectId`	NEW: Learning Plan	`/api/learning-plan?subjectId=`	AiStudyCoach
`/student/topic/:topicId`	NEW: Topic Learning	`/api/topics/{id}/content`, `/api/resources`	AiCoach (hints, explanations)
`/student/courses`	Course List	`/api/courses`	AiTipBanner
`/student/courses/:id`	Course Detail	`/api/courses/{id}`	--
`/student/assignments`	Assignments	`/api/assignments`	--
`/student/grades`	Grades	`/api/grades`	AiGradeExplainer
`/student/attendance`	Attendance	`/api/attendance`	--
`/student/timetable`	Timetable	`/api/timetable`	--
`/student/profile`	Profile	`/api/user`	--

32.3 Teacher Pages (10)

Route	Page	Key APIs	AI Components
`/teacher/dashboard`	Teacher Dashboard	`/api/user`, `/api/analytics/class`	AiInsightsPanel, AiAlertBanner
`/teacher/courses`	Courses	`/api/courses`	--
`/teacher/courses/new`	Course Builder	`/api/courses`, `/api/subjects/{id}/taxonomy`	AiCreationAssistant
`/teacher/courses/:id/edit`	Edit Course	`/api/courses/{id}`	AiCreationAssistant
`/teacher/assignments`	Assignments	`/api/assignments`	AiCreationAssistant
`/teacher/assignments/:id`	Assignment Detail / Grading	`/api/assignments/{id}`, `/api/evaluate/*`	AiGradingAssistant
`/teacher/attendance`	Attendance	`/api/attendance`	AiRiskBadge
`/teacher/students`	Students	`/api/users/list?type=student`	AiRiskBadge
`/teacher/timetable`	Timetable	`/api/timetable`	--
`/teacher/profile`	Profile	`/api/user`	--

32.4 Admin Pages (30+)

Route	Page	Key APIs	AI Components
`/admin/dashboard`	LMS Dashboard	`/api/analytics/subject`, `/api/courses`	AiInsightsPanel, AiAlertBanner
`/admin/platform`	Platform Dashboard	`/api/users/list`, entity counts	AiInsightsPanel
`/admin/courses`	Course Management	`/api/courses`	AiCreationAssistant
`/admin/students`	Student Management	`/api/users/list?type=student`	AiRiskBadge
`/admin/teachers`	Teacher Management	`/api/users/list?type=teacher`	--
`/admin/batches`	Batch Management	`/api/batches`	AiBatchOptimizer
`/admin/batches/:id`	Batch Detail	`/api/batches/{id}`	AiBatchOptimizer
`/admin/timetable`	Timetable Admin	`/api/timetable`	--
`/admin/reports`	Reports / Analytics	`/api/analytics/*`	AiReportNarrative
`/admin/settings`	LMS Settings	Configuration APIs	--
`/admin/assignments`	Assignments	`/api/assignments`	AiCreationAssistant
`/admin/examsList`	Exams List + Rubrics	`/api/exam`	--
`/admin/exam-structures`	Exam Structures	`/api/exam-structures`	--
`/admin/rubrics`	Rubrics	`/api/rubrics`	AiCreationAssistant
`/admin/generation`	Exam Generation	`/api/exam/*/generate`	AiGeneratorModal
`/admin/approval-workflows`	Approval Workflows	`/api/approval-workflows`	AiGradingAssistant
`/admin/users`	User Management	`/api/users/list`	--
`/admin/entities`	Entity Management	`/api/entities`	--
`/admin/classrooms`	Classroom Management	`/api/groups`	--
`/admin/taxonomy`	NEW: Taxonomy Manager	`/api/subjects`, `/api/domains`, `/api/topics`	--
`/admin/resources`	NEW: Resource Manager	`/api/resources`, `/api/analytics/content-gaps`	--
`/admin/adaptive-analytics`	NEW: Adaptive Analytics	`/api/analytics/subject`, `/api/analytics/content-gaps`	AiInsightsPanel
`/admin/student-performance`	Student Performance	`/api/proficiency/class`	AiStudyCoach, AiGradeExplainer
`/admin/stats-corporate`	Corporate Stats	`/api/statistical`	--
`/admin/record`	Record	`/api/stats`	--
`/admin/training/vocabulary`	Vocabulary	`/api/training`, FAISS tips	--
`/admin/training/grammar`	Grammar	`/api/training`, FAISS tips	--
`/admin/payment-record`	Payment Record	`/api/packages`, payment APIs	--
`/admin/tickets`	Tickets	`/api/tickets`	--
`/admin/settings-platform`	Platform Settings	Settings APIs	--
`/admin/exam`	Exam Runner	`/api/exam`, `/api/sessions`	--
`/admin/profile`	Admin Profile	`/api/user`	--

33. Non-Functional Requirements

ID	Requirement
NFR-SEC-01	Authorize on server/API; do not rely on hiding UI alone
NFR-SEC-02	Students can only access their own proficiency and learning plan data
NFR-SEC-03	AI prompts never include student personal data
NFR-SEC-04	Resource uploads validated for file type (no executables)
NFR-PERF-01	Pagination and server-side filtering for all list views
NFR-PERF-02	Diagnostic question generation < 3 seconds
NFR-PERF-03	AI grading response < 10 seconds (writing/speaking < 60 seconds)
NFR-PERF-04	Learning plan generation < 10 seconds
NFR-PERF-05	AI content generation < 15 seconds
NFR-PERF-06	API response time < 2 seconds for standard CRUD
NFR-SCALE-01	200 concurrent students per subject
NFR-SCALE-02	500 topics per subject
NFR-SCALE-03	1,000 resources per subject
NFR-UX-01	Consistent search/filter/pagination patterns; empty states; loading feedback
NFR-UX-02	Math content rendered with KaTeX; IT code rendered with syntax highlighting
NFR-A11Y-01	Icon-only actions have accessible names
NFR-A11Y-02	All forms have proper labels and validation messages
NFR-DATA-01	Proficiency scores use weighted averages (never direct overwrite)
NFR-DATA-02	Learning plan changes are logged with user ID and timestamp
NFR-DATA-03	Resource deletions are soft-delete to preserve completion records

Appendix A: Odoo Module Inventory

#	Module	Status	Description
1	`encoach_core`	Existing	Users, entities, roles, permissions, codes, invites
2	`encoach_ai`	Existing	OpenAI service, constants, blacklist, token counting
3	`encoach_ai_media`	Existing	TTS (Polly), STT (Whisper), ELAI avatars
4	`encoach_ai_generation`	Existing	Exam content generation (extend for Math/IT prompts)
5	`encoach_ai_grading`	Existing	Writing/speaking grading (extend for Math/IT rubrics)
6	`encoach_exam`	Existing	Exam model (extend with `subject_id`, `topic_ids`)
7	`encoach_assignment`	Existing	Assignment management
8	`encoach_evaluation`	Existing	Evaluation and AI job tracking
9	`encoach_stats`	Existing	Sessions and statistics (extend with `topic_id`, `subject_id`)
10	`encoach_training`	Existing	Training tips and walkthroughs (extend with `subject_id`)
11	`encoach_classroom`	Existing	Classroom groups
12	`encoach_subscription`	Existing	Packages, payments, discounts
13	`encoach_registration`	Existing	User registration and batch import
14	`encoach_ticket`	Existing	Support tickets
15	`encoach_api`	Existing	REST API controllers (extend with new endpoints)
16	`encoach_taxonomy`	NEW	Subject, domain, topic, learning objective models
17	`encoach_resources`	NEW	Learning resource library
18	`encoach_adaptive`	NEW	Proficiency, learning plans, progress tracking, content cache
19	`encoach_adaptive_api`	NEW	REST controllers for adaptive learning
20	`encoach_adaptive_ai`	NEW	AI services for diagnostics, plans, coaching, content
21	`encoach_lms_api`	NEW	REST API bridge for OpenEduCat models
22	`encoach_sis`	NEW	UTAS SIS integration (sync, mapping)
23	`encoach_branding`	NEW	Whitelabeling configuration

Total: 15 existing + 8 new = 23 modules

Appendix B: Implementation Priority

Priority	Components	Rationale
P0	Auth, core user management, taxonomy models, resource model	Platform foundation; blocks everything
P1	Diagnostic engine, proficiency profile, learning plan generation	Core adaptive learning loop
P1	Exam engine with multi-subject support	Exam generation and delivery
P2	LMS API bridge (OpenEduCat), course/batch/timetable/attendance	LMS functionality
P2	Content delivery (hybrid), practice questions, mastery quizzes	Learning content consumption
P2	AI components wiring (all 15 frontend components to real backend)	AI integration
P3	AI coaching (hints, explanations, study suggestions)	Learning enhancement
P3	Spaced repetition, analytics dashboards	Progress optimization
P3	SIS integration, whitelabeling	University integration
P4	Content gap detection, FAISS tips per subject, batch optimizer	Operational efficiency
P4	Payment system, subscription management	Commercial features

This is the definitive SRS for the new EnCoach platform. All previous SRS documents (SRS-EnCoach.md, MATH_IT_ADAPTIVE_LEARNING_SRS.md, ODOO_MIGRATION_SRS_v2.md) are superseded by this document for new development.

60 KiB Raw Blame History