encoach_frontend_new_v1/docs/ENCOACH_UNIFIED_SRS.md

# 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

---

## Table of Contents

**Part I -- Platform Foundation**
1. [Introduction](#1-introduction)
2. [System Architecture](#2-system-architecture)
3. [User Roles and Multi-Tenancy](#3-user-roles-and-multi-tenancy)
4. [Authentication and Authorization](#4-authentication-and-authorization)
5. [Global UI Shell](#5-global-ui-shell)

**Part II -- Universal Subject Engine**
6. [Subject Taxonomy](#6-subject-taxonomy)
7. [Diagnostic Assessment](#7-diagnostic-assessment)
8. [Proficiency Profile](#8-proficiency-profile)
9. [Learning Plan Generation](#9-learning-plan-generation)
10. [Hybrid Content Delivery](#10-hybrid-content-delivery)
11. [Progress Tracking and Mastery](#11-progress-tracking-and-mastery)

**Part III -- LMS Module**
12. [Course Management](#12-course-management)
13. [Batch and Enrollment](#13-batch-and-enrollment)
14. [Timetable and Attendance](#14-timetable-and-attendance)
15. [Gradebook and Reports](#15-gradebook-and-reports)

**Part IV -- Exam Engine**
16. [Exam Management](#16-exam-management)
17. [AI Content Generation](#17-ai-content-generation)
18. [Exam Delivery](#18-exam-delivery)
19. [AI Grading](#19-ai-grading)

**Part V -- AI Services**
20. [AI Services Catalog](#20-ai-services-catalog)
21. [AI Integration in Frontend](#21-ai-integration-in-frontend)

**Part VI -- Administration**
22. [User Management](#22-user-management)
23. [Entity Management](#23-entity-management)
24. [Classroom Management](#24-classroom-management)
25. [Assignment Management](#25-assignment-management)
26. [Permission Management](#26-permission-management)

**Part VII -- Support and Commercial**
27. [Ticketing System](#27-ticketing-system)
28. [Subscriptions and Payments](#28-subscriptions-and-payments)
29. [Training Content](#29-training-content)

**Part VIII -- Technical Specifications**
30. [Data Models](#30-data-models)
31. [REST API Specification](#31-rest-api-specification)
32. [Frontend Page Inventory](#32-frontend-page-inventory)
33. [Non-Functional Requirements](#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

```mermaid
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

```mermaid
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

### 5.1 Navbar

| 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 |

### 5.2 Sidebar Navigation

| 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

1. **Topological sort** -- order topics respecting prerequisites
2. **Filter mastered** -- exclude topics with mastery >= threshold
3. **Prioritize** -- lowest mastery first, balanced across domains
4. **Estimate duration** -- based on topic complexity and current mastery
5. **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

1. **Human-uploaded resources** tagged to the topic (PDFs, videos, links)
2. **AI-generated content** if no human resources exist (explanations, worked examples, summaries)
3. **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 | New frontend |

---

# 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.*