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 -- Institutional LMS (OpenEduCat)**
30. [Academic Year and Term Management](#30-academic-year-and-term-management)
31. [Department Management](#31-department-management)
32. [Admission and Enrollment](#32-admission-and-enrollment)
33. [Subject Registration](#33-subject-registration)
34. [Institutional Exam Sessions](#34-institutional-exam-sessions)
35. [Assignment File Submissions](#35-assignment-file-submissions)

**Part IX -- Technical Specifications**
36. [Data Models](#36-data-models)
37. [REST API Specification](#37-rest-api-specification)
38. [Frontend Page Inventory](#38-frontend-page-inventory)
39. [Non-Functional Requirements](#39-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, Subject Registration, 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 |
| **Institutional** | Academic Years, Departments, Admissions, Exam Sessions, Marksheets |
| **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 -- Institutional LMS (OpenEduCat)

All LMS features in this part are backed by OpenEduCat community modules (ported to Odoo 19). The `encoach_lms_api` module extends these models and exposes them via REST API to the React frontend.

---

## 30. Academic Year and Term Management

### 30.1 Overview

Academic years define the institutional calendar. Each year contains terms (semesters, quarters) that govern course scheduling, batch periods, and exam sessions.

### 30.2 Data Models (OpenEduCat)

**`op.academic.year`**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Academic year name (e.g., "2026-2027") |
| `start_date` | Date | Year start |
| `end_date` | Date | Year end |
| `term_structure` | Selection | `two_sem`, `two_sem_qua`, `three_sem`, `four_Quarter`, `final_year`, `others` |
| `academic_term_ids` | One2many | Terms within this year |

**`op.academic.term`**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Term name (e.g., "Semester 1") |
| `term_start_date` | Date | Term start |
| `term_end_date` | Date | Term end |
| `academic_year_id` | Many2one | Parent academic year |
| `parent_term` | Many2one | Parent term (for quarters within semesters) |

### 30.3 Functional Requirements

| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-AY-01 | List academic years with terms | `/admin/academic-years` | Admin |
| FR-AY-02 | Create academic year with term structure selection | `/admin/academic-years` | Admin |
| FR-AY-03 | Auto-generate terms based on selected structure | `/admin/academic-years` | Admin |
| FR-AY-04 | Edit/delete academic years and terms | `/admin/academic-years` | Admin |
| FR-AY-05 | Link batches and courses to academic terms | Related pages | Admin |

### 30.4 API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/academic-years` | List academic years |
| `POST` | `/api/academic-years` | Create academic year |
| `GET` | `/api/academic-years/{id}` | Get year with terms |
| `PATCH` | `/api/academic-years/{id}` | Update year |
| `DELETE` | `/api/academic-years/{id}` | Delete year |
| `POST` | `/api/academic-years/{id}/generate-terms` | Auto-generate terms from structure |
| `GET` | `/api/academic-terms` | List terms (filter by year) |
| `POST` | `/api/academic-terms` | Create term |
| `PATCH` | `/api/academic-terms/{id}` | Update term |
| `DELETE` | `/api/academic-terms/{id}` | Delete term |

---

## 31. Department Management

### 31.1 Overview

Departments organize faculty, courses, and subjects into academic units (e.g., "Department of Mathematics", "Department of IT").

### 31.2 Data Model (OpenEduCat)

**`op.department`**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Department name |
| `code` | Char | Department code |
| `parent_id` | Many2one | Parent department (for hierarchy) |

### 31.3 Functional Requirements

| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-DEPT-01 | List departments | `/admin/departments` | Admin |
| FR-DEPT-02 | Create/edit department | `/admin/departments` | Admin |
| FR-DEPT-03 | Delete department | `/admin/departments` | Admin |
| FR-DEPT-04 | Assign department to courses and faculty | Related pages | Admin |

### 31.4 API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/departments` | List departments |
| `POST` | `/api/departments` | Create department |
| `PATCH` | `/api/departments/{id}` | Update department |
| `DELETE` | `/api/departments/{id}` | Delete department |

---

## 32. Admission and Enrollment

### 32.1 Overview

The admission workflow manages student applications from submission through confirmation to enrollment. Admission registers define open enrollment windows.

### 32.2 Data Models (OpenEduCat)

**`op.admission.register`**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Register name (e.g., "Fall 2026 Admissions") |
| `course_id` | Many2one | Target course |
| `start_date` | Date | Application window start |
| `end_date` | Date | Application window end |
| `min_count` | Integer | Minimum applications to proceed |
| `max_count` | Integer | Maximum applications accepted |
| `state` | Selection | `draft`, `confirm`, `cancel`, `done` |
| `product_id` | Many2one | Fee product for admission |

**`op.admission`**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Applicant name |
| `application_number` | Char | Auto-generated application number |
| `register_id` | Many2one | Admission register |
| `course_id` | Many2one | Applied course |
| `batch_id` | Many2one | Target batch |
| `first_name` | Char | First name |
| `middle_name` | Char | Middle name |
| `last_name` | Char | Last name |
| `email` | Char | Email |
| `phone` | Char | Phone |
| `birth_date` | Date | Date of birth |
| `gender` | Selection | `m`, `f`, `o` |
| `nationality` | Many2one | Country |
| `state` | Selection | `draft`, `submit`, `confirm`, `admission`, `reject`, `cancel`, `done` |
| `fees` | Float | Admission fee amount |
| `image` | Binary | Applicant photo |
| `student_id` | Many2one | Created student record (after admission) |

### 32.3 Functional Requirements

| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-ADM-01 | List admission registers with status | `/admin/admission-register` | Admin |
| FR-ADM-02 | Create/edit admission register (course, dates, capacity) | `/admin/admission-register` | Admin |
| FR-ADM-03 | Open/close admission register | `/admin/admission-register` | Admin |
| FR-ADM-04 | List admissions with filters (status, course, register) | `/admin/admissions` | Admin |
| FR-ADM-05 | View admission detail | `/admin/admissions/:id` | Admin |
| FR-ADM-06 | Transition admission status (submit, confirm, admit, reject) | `/admin/admissions/:id` | Admin |
| FR-ADM-07 | On admit: auto-create `op.student` and `op.student.course` records | Backend | System |
| FR-ADM-08 | Public admission application form | `/apply` | Public/Student |
| FR-ADM-09 | Applicant status tracking | `/apply/status` | Public |

### 32.4 API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/admission-registers` | List registers |
| `POST` | `/api/admission-registers` | Create register |
| `PATCH` | `/api/admission-registers/{id}` | Update register |
| `POST` | `/api/admission-registers/{id}/confirm` | Confirm register |
| `POST` | `/api/admission-registers/{id}/close` | Close register |
| `GET` | `/api/admissions` | List admissions |
| `GET` | `/api/admissions/{id}` | Get admission detail |
| `POST` | `/api/admissions` | Submit admission application |
| `POST` | `/api/admissions/{id}/submit` | Submit for review |
| `POST` | `/api/admissions/{id}/confirm` | Confirm admission |
| `POST` | `/api/admissions/{id}/admit` | Admit applicant (creates student) |
| `POST` | `/api/admissions/{id}/reject` | Reject admission |

---

## 33. Subject Registration

### 33.1 Overview

Within enrolled courses, students register for specific subjects. This is required for timetable, attendance, and exam eligibility.

### 33.2 Data Model (OpenEduCat)

**`op.subject.registration`**

| Field | Type | Description |
|-------|------|-------------|
| `student_id` | Many2one | Student |
| `course_id` | Many2one | Course |
| `batch_id` | Many2one | Batch |
| `subject_ids` | Many2many | Selected subjects |
| `min_unit_load` | Float | Minimum units from course config |
| `max_unit_load` | Float | Maximum units from course config |
| `state` | Selection | `draft`, `confirm`, `reject`, `done` |

### 33.3 Functional Requirements

| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-SR-01 | Students view available subjects for enrolled courses | `/student/subject-registration` | Student |
| FR-SR-02 | Students select subjects within unit load limits | `/student/subject-registration` | Student |
| FR-SR-03 | Submit registration for approval | `/student/subject-registration` | Student |
| FR-SR-04 | Admin/teacher view and approve/reject registrations | `/admin/students` | Admin |
| FR-SR-05 | Confirmed registration updates `op.student.course.subject_ids` | Backend | System |

### 33.4 API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/subject-registrations` | List registrations (filter by student, course, status) |
| `POST` | `/api/subject-registrations` | Create registration |
| `PATCH` | `/api/subject-registrations/{id}` | Update subjects |
| `POST` | `/api/subject-registrations/{id}/confirm` | Confirm registration |
| `POST` | `/api/subject-registrations/{id}/reject` | Reject registration |
| `GET` | `/api/subject-registrations/available` | Get available subjects for current student |

---

## 34. Institutional Exam Sessions

### 34.1 Overview

Institutional exam sessions group traditional exams (midterms, finals) for a course/batch. These are separate from EnCoach AI-powered exams. They use the OpenEduCat exam, marksheet, and grading system.

### 34.2 Data Models (OpenEduCat)

**`op.exam.session`**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Session name (e.g., "Fall 2026 Midterms") |
| `course_id` | Many2one | Course |
| `batch_id` | Many2one | Batch |
| `exam_code` | Char | Session code |
| `start_date` | Date | Session start |
| `end_date` | Date | Session end |
| `exam_type` | Many2one | Exam type (midterm, final, quiz) |
| `evaluation_type` | Selection | `normal` or `grade` |
| `venue` | Many2one | Venue partner |
| `state` | Selection | `draft`, `schedule`, `held`, `cancel`, `done` |
| `exam_ids` | One2many | Exams in this session |

**`op.exam` (institutional)**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Exam name |
| `session_id` | Many2one | Parent session |
| `subject_id` | Many2one | Subject being examined |
| `exam_code` | Char | Exam code |
| `start_time` | Datetime | Exam start |
| `end_time` | Datetime | Exam end |
| `total_marks` | Integer | Maximum marks |
| `min_marks` | Integer | Passing marks |
| `state` | Selection | `draft`, `schedule`, `held`, `result_updated`, `cancel`, `done` |
| `responsible_id` | Many2many | Responsible faculty |
| `attendees_line` | One2many | Exam attendees with marks |

**`op.exam.type`**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Type name (Midterm, Final, Quiz, Lab) |

**`op.exam.room`**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Room name |
| `classroom_id` | Many2one | Linked classroom |
| `capacity` | Integer | Room capacity |

**`op.exam.attendees`**

| Field | Type | Description |
|-------|------|-------------|
| `exam_id` | Many2one | Exam |
| `student_id` | Many2one | Student |
| `room_id` | Many2one | Assigned room |
| `marks` | Integer | Obtained marks |
| `status` | Selection | `pass`, `fail` (computed from marks vs min_marks) |

**`op.marksheet.register`**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Register name |
| `exam_session_id` | Many2one | Exam session |
| `marksheet_line` | One2many | Marksheet lines per student |
| `result_template_id` | Many2one | Result template |
| `state` | Selection | `draft`, `validated`, `cancelled` |
| `total_pass` | Integer | Computed pass count |
| `total_failed` | Integer | Computed fail count |

**`op.marksheet.line`**

| Field | Type | Description |
|-------|------|-------------|
| `student_id` | Many2one | Student |
| `marksheet_reg_id` | Many2one | Parent register |
| `result_line` | One2many | Per-exam results |
| `total_marks` | Integer | Computed total |
| `percentage` | Float | Computed percentage |
| `grade` | Char | Computed grade (if grade evaluation) |
| `status` | Selection | `pass`, `fail` (computed) |

**`op.result.line`**

| Field | Type | Description |
|-------|------|-------------|
| `marksheet_line_id` | Many2one | Parent marksheet line |
| `exam_id` | Many2one | Exam |
| `student_id` | Many2one | Student |
| `marks` | Integer | Marks obtained |
| `grade` | Char | Computed grade |
| `status` | Selection | `pass`, `fail` (computed from marks vs min_marks) |

**`op.result.template`**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Template name |
| `exam_session_id` | Many2one | Exam session |
| `grade_ids` | Many2many | Grade configuration rules |
| `result_date` | Date | Result publication date |
| `state` | Selection | `draft`, `result_generated` |

**`op.grade.configuration`**

| Field | Type | Description |
|-------|------|-------------|
| `min_per` | Integer | Minimum percentage |
| `max_per` | Integer | Maximum percentage |
| `result` | Char | Grade display (e.g., "A", "B+", "Pass") |

### 34.3 Functional Requirements

| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-IEX-01 | List exam sessions with status filters | `/admin/exam-sessions` | Admin |
| FR-IEX-02 | Create exam session (course, batch, dates, type) | `/admin/exam-sessions` | Admin |
| FR-IEX-03 | Add exams to session (subject, time, marks) | `/admin/exam-sessions` | Admin |
| FR-IEX-04 | Schedule and manage session state transitions | `/admin/exam-sessions` | Admin |
| FR-IEX-05 | Enter marks for exam attendees | `/admin/exam-sessions` | Admin/Teacher |
| FR-IEX-06 | Configure grade scales | `/admin/marksheets` | Admin |
| FR-IEX-07 | Create result templates and generate marksheets | `/admin/marksheets` | Admin |
| FR-IEX-08 | View marksheet results (pass/fail, grades, percentages) | `/admin/marksheets` | Admin |
| FR-IEX-09 | Students view institutional exam results | `/student/grades` | Student |

### 34.4 API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/inst-exam-sessions` | List exam sessions |
| `POST` | `/api/inst-exam-sessions` | Create session |
| `GET` | `/api/inst-exam-sessions/{id}` | Get session with exams |
| `PATCH` | `/api/inst-exam-sessions/{id}` | Update session |
| `DELETE` | `/api/inst-exam-sessions/{id}` | Delete session |
| `POST` | `/api/inst-exam-sessions/{id}/schedule` | Schedule session |
| `POST` | `/api/inst-exam-sessions/{id}/done` | Mark session done |
| `POST` | `/api/inst-exams` | Add exam to session |
| `PATCH` | `/api/inst-exams/{id}` | Update exam |
| `POST` | `/api/inst-exams/{id}/attendees` | Add attendees |
| `PATCH` | `/api/inst-exams/{id}/marks` | Enter marks |
| `GET` | `/api/exam-types` | List exam types |
| `POST` | `/api/exam-types` | Create exam type |
| `GET` | `/api/grade-config` | List grade configurations |
| `POST` | `/api/grade-config` | Create grade config |
| `GET` | `/api/result-templates` | List result templates |
| `POST` | `/api/result-templates` | Create result template |
| `POST` | `/api/result-templates/{id}/generate` | Generate marksheets |
| `GET` | `/api/marksheets` | List marksheets |
| `GET` | `/api/marksheets/{id}` | Get marksheet with results |
| `POST` | `/api/marksheets/{id}/validate` | Validate marksheet |

---

## 35. Assignment File Submissions

### 35.1 Overview

Traditional course assignments where students submit files and teachers grade them. Coexists with EnCoach exam-wrapper assignments (`encoach.assignment`).

### 35.2 Data Models (OpenEduCat)

**`grading.assignment.type`**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Type name (Homework, Project, Lab Report, Presentation) |

**`grading.assignment`**

| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Assignment title |
| `course_id` | Many2one | Course |
| `subject_id` | Many2one | Subject |
| `issued_date` | Datetime | Issue date |
| `assignment_type` | Many2one | Assignment type |
| `faculty_id` | Many2one | Issuing faculty |
| `point` | Float | Maximum points |

**`op.assignment` (extends `grading.assignment`)**

| Field | Type | Description |
|-------|------|-------------|
| `batch_id` | Many2one | Batch |
| `marks` | Float | Maximum marks |
| `description` | Text | Assignment description |
| `state` | Selection | `draft`, `publish`, `finish`, `cancel` |
| `submission_date` | Datetime | Submission deadline |
| `allocation_ids` | Many2many | Allocated students |
| `assignment_sub_line` | One2many | Student submissions |
| `reviewer` | Many2one | Reviewing faculty |

**`op.assignment.sub.line`**

| Field | Type | Description |
|-------|------|-------------|
| `assignment_id` | Many2one | Parent assignment |
| `student_id` | Many2one | Submitting student |
| `description` | Text | Submission notes |
| `submission_date` | Datetime | Actual submission time |
| `attachment_ids` | Many2many | Uploaded files |
| `marks` | Float | Awarded marks |
| `state` | Selection | `draft`, `submit`, `accept`, `reject`, `change_req` |
| `faculty_id` | Many2one | Grading faculty |
| `note` | Text | Faculty feedback |

### 35.3 Functional Requirements

| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-SUB-01 | Teacher creates course assignment with description, deadline, files | `/teacher/assignments` | Teacher |
| FR-SUB-02 | Teacher publishes assignment (visible to allocated students) | `/teacher/assignments` | Teacher |
| FR-SUB-03 | Student views assigned course assignments with deadlines | `/student/assignments` | Student |
| FR-SUB-04 | Student uploads files as submission | `/student/assignments` | Student |
| FR-SUB-05 | Teacher views submissions per assignment | `/teacher/assignments/:id` | Teacher |
| FR-SUB-06 | Teacher grades submission (marks, feedback, accept/reject/change request) | `/teacher/assignments/:id` | Teacher |
| FR-SUB-07 | Admin views all course assignments across batches | `/admin/assignments` | Admin |

### 35.4 API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/course-assignments` | List course assignments |
| `POST` | `/api/course-assignments` | Create assignment |
| `GET` | `/api/course-assignments/{id}` | Get assignment with submissions |
| `PATCH` | `/api/course-assignments/{id}` | Update assignment |
| `POST` | `/api/course-assignments/{id}/publish` | Publish assignment |
| `POST` | `/api/course-assignments/{id}/finish` | Close assignment |
| `GET` | `/api/course-assignments/{id}/submissions` | List submissions |
| `POST` | `/api/course-assignments/{id}/submit` | Student submits (multipart file upload) |
| `PATCH` | `/api/submissions/{id}` | Grade submission (marks, feedback, status) |
| `GET` | `/api/assignment-types` | List assignment types |
| `POST` | `/api/assignment-types` | Create assignment type |

---

# Part IX -- Technical Specifications

## 36. Data Models

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

### 36.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` |

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

### 36.4 New Models (Branding)

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

---

## 37. REST API Specification

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

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

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

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

### 37.5 New Endpoints (OpenEduCat Institutional LMS, 60+)

| Group | Method | Path | Description |
|-------|--------|------|-------------|
| **Academic Years** | `GET/POST` | `/api/academic-years` | List/create years |
| | `GET/PATCH/DELETE` | `/api/academic-years/{id}` | Year CRUD |
| | `POST` | `/api/academic-years/{id}/generate-terms` | Auto-generate terms |
| | `GET/POST` | `/api/academic-terms` | List/create terms |
| | `PATCH/DELETE` | `/api/academic-terms/{id}` | Term CRUD |
| **Departments** | `GET/POST` | `/api/departments` | List/create |
| | `PATCH/DELETE` | `/api/departments/{id}` | CRUD |
| **Admissions** | `GET/POST` | `/api/admission-registers` | List/create registers |
| | `PATCH` | `/api/admission-registers/{id}` | Update |
| | `POST` | `/api/admission-registers/{id}/confirm` | Confirm register |
| | `POST` | `/api/admission-registers/{id}/close` | Close register |
| | `GET/POST` | `/api/admissions` | List/create admissions |
| | `GET` | `/api/admissions/{id}` | Admission detail |
| | `POST` | `/api/admissions/{id}/submit` | Submit for review |
| | `POST` | `/api/admissions/{id}/confirm` | Confirm |
| | `POST` | `/api/admissions/{id}/admit` | Admit (creates student) |
| | `POST` | `/api/admissions/{id}/reject` | Reject |
| **Subject Registration** | `GET/POST` | `/api/subject-registrations` | List/create |
| | `PATCH` | `/api/subject-registrations/{id}` | Update subjects |
| | `POST` | `/api/subject-registrations/{id}/confirm` | Confirm |
| | `POST` | `/api/subject-registrations/{id}/reject` | Reject |
| | `GET` | `/api/subject-registrations/available` | Available subjects |
| **Inst. Exam Sessions** | `GET/POST` | `/api/inst-exam-sessions` | List/create |
| | `GET/PATCH/DELETE` | `/api/inst-exam-sessions/{id}` | CRUD |
| | `POST` | `/api/inst-exam-sessions/{id}/schedule` | Schedule |
| | `POST` | `/api/inst-exam-sessions/{id}/done` | Mark done |
| | `POST` | `/api/inst-exams` | Add exam |
| | `PATCH` | `/api/inst-exams/{id}` | Update exam |
| | `POST` | `/api/inst-exams/{id}/attendees` | Add attendees |
| | `PATCH` | `/api/inst-exams/{id}/marks` | Enter marks |
| | `GET/POST` | `/api/exam-types` | List/create types |
| | `GET/POST` | `/api/grade-config` | Grade configuration |
| | `GET/POST` | `/api/result-templates` | Result templates |
| | `POST` | `/api/result-templates/{id}/generate` | Generate marksheets |
| | `GET` | `/api/marksheets` | List marksheets |
| | `GET` | `/api/marksheets/{id}` | Marksheet detail |
| | `POST` | `/api/marksheets/{id}/validate` | Validate |
| **Course Assignments** | `GET/POST` | `/api/course-assignments` | List/create |
| | `GET/PATCH` | `/api/course-assignments/{id}` | CRUD |
| | `POST` | `/api/course-assignments/{id}/publish` | Publish |
| | `POST` | `/api/course-assignments/{id}/finish` | Close |
| | `GET` | `/api/course-assignments/{id}/submissions` | List submissions |
| | `POST` | `/api/course-assignments/{id}/submit` | Student submits |
| | `PATCH` | `/api/submissions/{id}` | Grade submission |
| | `GET/POST` | `/api/assignment-types` | Assignment types |

---

## 38. Frontend Page Inventory

### 38.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` |

### 38.2 Student Pages (12+)

| 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` | -- |
| `/student/subject-registration` | **NEW:** Subject Registration | `/api/subject-registrations/available`, `/api/subject-registrations` | -- |

### 38.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` | -- |

### 38.4 Public Pages (2)

| Route | Page | Key APIs | AI Components |
|-------|------|----------|---------------|
| `/apply` | **NEW:** Admission Application | `/api/admissions`, `/api/admission-registers` | -- |
| `/apply/status` | **NEW:** Application Status | `/api/admissions/{id}` | -- |

### 38.5 Admin Pages (38+)

| 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` | -- |
| `/admin/academic-years` | **NEW:** Academic Year Manager | `/api/academic-years`, `/api/academic-terms` | -- |
| `/admin/departments` | **NEW:** Department Manager | `/api/departments` | -- |
| `/admin/admissions` | **NEW:** Admission List | `/api/admissions` | -- |
| `/admin/admissions/:id` | **NEW:** Admission Detail | `/api/admissions/{id}` | -- |
| `/admin/admission-register` | **NEW:** Admission Register | `/api/admission-registers` | -- |
| `/admin/exam-sessions` | **NEW:** Institutional Exam Sessions | `/api/inst-exam-sessions`, `/api/inst-exams` | -- |
| `/admin/marksheets` | **NEW:** Marksheet Manager | `/api/marksheets`, `/api/result-templates`, `/api/grade-config` | -- |

---

## 39. 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 (extends `op.course`, `op.batch`, adds missing fields) |
| 22 | `encoach_sis` | **NEW** | UTAS SIS integration (sync, mapping) |
| 23 | `encoach_branding` | **NEW** | Whitelabeling configuration |
| 24 | `openeducat_core` | **OpenEduCat (port to v19)** | `op.course`, `op.batch`, `op.student`, `op.faculty`, `op.subject`, `op.department`, `op.category`, `op.academic.year`, `op.academic.term`, `op.student.course`, `op.subject.registration` |
| 25 | `openeducat_timetable` | **OpenEduCat (port to v19)** | `op.session`, `op.timing` |
| 26 | `openeducat_attendance` | **OpenEduCat (port to v19)** | `op.attendance.register`, `op.attendance.sheet`, `op.attendance.line`, `op.attendance.type` |
| 27 | `openeducat_classroom` | **OpenEduCat (port to v19)** | `op.classroom` (physical rooms) |
| 28 | `openeducat_exam` | **OpenEduCat (port to v19)** | `op.exam.session`, `op.exam`, `op.exam.type`, `op.exam.attendees`, `op.exam.room`, `op.marksheet.register`, `op.marksheet.line`, `op.result.line`, `op.result.template`, `op.grade.configuration` |
| 29 | `openeducat_assignment` | **OpenEduCat (port to v19)** | `op.assignment`, `op.assignment.sub.line`, `grading.assignment`, `grading.assignment.type` |
| 30 | `openeducat_admission` | **OpenEduCat (port to v19)** | `op.admission`, `op.admission.register` |
| 31 | `openeducat_facility` | **OpenEduCat (port to v19)** | `op.facility`, `op.facility.line` (dependency of classroom) |

**Total: 15 existing EnCoach + 8 new EnCoach + 8 OpenEduCat = 31 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** | OpenEduCat porting (v17→v19), LMS API bridge, course/batch/timetable/attendance | LMS functionality |
| **P2** | Academic years/terms, departments, admission workflow | Institutional operations |
| **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** | Institutional exam sessions, marksheets, subject registration | Institutional assessment |
| **P3** | Course assignment submissions (file upload, grading) | Homework workflow |
| **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.*