devops/encoach_frontend_new_v2
1
0
Fork 0
Code Issues Pull Requests 4 Actions Packages Projects Releases Wiki Activity
Files
c9bf12ad8ea226c8a18d670ebdaa0bade390595a
encoach_frontend_new_v2/docs/ENCOACH_UNIFIED_SRS.md
devops 4383db7fa1 docs: update all SRS documents to reflect implemented state 
- ENCOACH_UNIFIED_SRS.md v2.0: updated header, added 8 new Part VIII-B
  sections (student leave, fees, lessons, gradebook, student progress,
  library, activities, facilities), extended permissions with roles CRUD
  and authority matrix, updated tech specs (93 pages, ~377 API routes,
  41 modules), added implementation traceability to all sections
- ENCOACH_ODOO19_BACKEND_SRS.md v3.0: updated status to implemented,
  added beyond-SRS features section, updated module count to 41,
  endpoint count to ~377
- ODOO_DEVELOPER_HANDOFF.md: rewritten with current repo references
  and implementation status
- ENCOACH_SYSTEM_FEATURES_GUIDE.md: added system features guide
- Superseded notices added to ODOO_BACKEND_SRS_v3.md,
  ODOO_MIGRATION_SRS_v2.md, ODOO_MIGRATION_SRS.md,
  ODOO_MIGRATION_FRONTEND_SRS.md, MATH_IT_ADAPTIVE_LEARNING_SRS.md

Made-with: Cursor
2026-04-06 12:57:52 +04:00

3224 lines
153 KiB
Markdown
Raw Blame History

# EnCoach Unified Platform -- Software Requirements Specification
**Document Version:** 2.0
**Date:** March 11, 2026
**Status:** Implemented -- Staging Verified
**Supersedes:** `ielts-ui/SRS-EnCoach.md` (v2.0), `MATH_IT_ADAPTIVE_LEARNING_SRS.md` (v1.0), `ENCOACH_UNIFIED_SRS.md` (v1.0)
**Author:** EnCoach Engineering Team
### Implementation Status
| Artifact | Location |
|----------|----------|
| **Frontend Repository** | `https://git.albousalh.com/devops/encoach_frontend_new_v2.git` (branch: `main`) |
| **Backend Repository** | `https://git.albousalh.com/devops/encoach_backend_new_v2.git` (branch: `main`) |
| **Staging Frontend** | `http://5.189.151.117:3000` |
| **Staging Backend (Odoo 19)** | `http://5.189.151.117:8069` |
| **Frontend Stack** | React 18, TypeScript, Vite 5, shadcn/ui, TanStack Query, React Router v6 |
| **Backend Stack** | Odoo 19, Python 3.11, PostgreSQL 16, Docker Compose |
| **Frontend Pages** | 93 page components (28 root, 33 admin, 19 student, 14 teacher) |
| **Frontend Services** | 37 API service modules |
| **Frontend Types** | 29 TypeScript type definition files |
| **Frontend Query Hooks** | 21 TanStack Query hook modules |
| **Backend Custom Modules** | 27 `encoach_*` modules |
| **Backend OpenEduCat Modules** | 14 `openeducat_*` community modules |
| **Backend API Routes** | ~377 REST endpoints across 4 controller packages |
All sections in this SRS have been implemented in both frontend and backend unless otherwise noted. The developer implemented all original SRS requirements plus additional OpenEduCat Enterprise-level features documented in Part VIII-B.
---
## 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 VIII-B -- OpenEduCat Enterprise Features**
36. [Student Leave Management](#36-student-leave-management)
37. [Fees Management](#37-fees-management)
38. [Lessons Management](#38-lessons-management)
39. [Gradebook and Grading Assignments](#39-gradebook-and-grading-assignments)
40. [Student Progress Tracking](#40-student-progress-tracking)
41. [Library Management](#41-library-management)
42. [Activity Management](#42-activity-management)
43. [Facility and Asset Management](#43-facility-and-asset-management)
**Part IX -- Courseware and Content Delivery**
44. [Course Chapters](#44-course-chapters)
45. [Chapter Materials](#45-chapter-materials)
46. [AI Workbench for Course Content](#46-ai-workbench-for-course-content)
**Part X -- Communication**
47. [Discussion Boards](#47-discussion-boards)
48. [Announcements](#48-announcements)
49. [Messaging](#49-messaging)
**Part XI -- Notifications and FAQ**
50. [Notification Engine](#50-notification-engine)
51. [FAQ System](#51-faq-system)
**Part XII -- Technical Specifications**
52. [Data Models](#52-data-models)
53. [REST API Specification](#53-rest-api-specification)
54. [Frontend Page Inventory](#54-frontend-page-inventory)
55. [Non-Functional Requirements](#55-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
> **Implementation:** `auth.service.ts` | `encoach_api/controllers/auth.py` | `Login.tsx`, `Register.tsx`, `ForgotPassword.tsx`
### 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, Discussions, Messages, Announcements, Journey, Profile
**Teacher sidebar:** Dashboard, Courses, Assignments, Attendance, Students, Timetable, Discussions, Announcements, 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
> **Implementation:** `taxonomy.service.ts` | `encoach_adaptive_api/controllers/taxonomy.py` | `AdminTaxonomy.tsx`
### 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
> **Implementation:** `adaptive.service.ts` | `encoach_adaptive_api/controllers/diagnostic.py` | `StudentDiagnostic.tsx`
### 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
> **Implementation:** `adaptive.service.ts` | `encoach_adaptive_api/controllers/proficiency.py` | `StudentProficiency.tsx`
### 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
> **Implementation:** `adaptive.service.ts` | `encoach_adaptive_api/controllers/learning_plan.py` | `StudentLearningPlan.tsx`
### 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
> **Implementation:** `adaptive.service.ts`, `resources.service.ts`, `coaching.service.ts` | `encoach_adaptive_api/controllers/content.py`, `encoach_resources/controllers/resources_rest.py` | `StudentTopic.tsx`
### 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
> **Implementation:** `adaptive.service.ts`, `analytics.service.ts` | `encoach_adaptive_api/controllers/content.py`, `encoach_api/controllers/ai_analytics.py` | `StudentJourney.tsx`, `AdminAdaptiveAnalytics.tsx`
### 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
> **Implementation:** `lms.service.ts` | `encoach_lms_api/controllers/courses.py` | `StudentCourses.tsx`, `TeacherCourses.tsx`, `AdminCourses.tsx`
### 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
> **Implementation:** `lms.service.ts` | `encoach_lms_api/controllers/batches.py` | `AdminBatches.tsx`
| 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
> **Implementation:** `lms.service.ts` | `encoach_lms_api/controllers/timetable.py`, `encoach_lms_api/controllers/attendance.py` | `StudentTimetable.tsx`, `TeacherTimetable.tsx`, `AdminTimetable.tsx`, `StudentAttendance.tsx`, `TeacherAttendance.tsx`
| 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
> **Implementation:** `lms.service.ts`, `analytics.service.ts` | `encoach_lms_api/controllers/grades.py`, `encoach_api/controllers/ai_analytics.py` | `StudentGrades.tsx`, `AdminReports.tsx`
| 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
> **Implementation:** `exams.service.ts` | `encoach_api/controllers/exam.py` | `AdminExamsList.tsx`, `AdminExamStructures.tsx`, `AdminRubrics.tsx`, `Exam.tsx`
### 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 |
| FR-EX-08 | **NEW:** Exercise vs Exam differentiation -- `is_exercise` flag; exercises are self-paced practice (no journey tracking), exams are official graded assessments | Client |
| FR-EX-09 | **NEW:** `is_official` flag on exams -- official exams track to student journey and support special access modes | Client |
| FR-EX-10 | **NEW:** Official exam access modes: (1) unique shareable link, (2) landing page access, (3) separate login screen | Client |
| FR-EX-11 | **NEW:** Exam activation control -- teacher sets start date, end date, activation status | Client |
| FR-EX-12 | **NEW:** Different exam for each student option (AI generates unique variants per student) | Client |
| FR-EX-13 | **NEW:** Configurable reminder frequency -- number of reminders, notification via email and system notification | Client |
| FR-EX-14 | **NEW:** Exam suspend/revoke actions | Client |
| FR-EX-15 | **NEW:** Student inquiry and extension requests on exams | Client |
### 16.2 Official Exam Access (NEW)
| Access Mode | Description | Route |
|-------------|-------------|-------|
| **Link Access** | Teacher generates a unique URL; students access exam via the link without full platform login | `/exam/access/{token}` |
| **Landing Page** | Exam appears on the public landing page; students authenticate with exam code + credentials | `/exam/official/{code}` |
| **Separate Login** | Dedicated login screen for the exam only; no access to other platform features | `/exam/login/{examId}` |
### 16.4 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.5 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
> **Implementation:** `generation.service.ts` | `encoach_api/controllers/generation.py` | `AdminGeneration.tsx`
### 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
> **Implementation:** `exams.service.ts`, `media.service.ts` | `encoach_api/controllers/exam.py`, `encoach_api/controllers/generation.py` | `Exam.tsx`, `OfficialExam.tsx`
### 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
> **Implementation:** `evaluations.service.ts`, `plagiarism.service.ts` | `encoach_api/controllers/generation.py`, `encoach_lms_api/controllers/plagiarism.py` | `AdminApprovalWorkflows.tsx`
### 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 Plagiarism Detection (NEW -- Implemented)
> **Implementation:** `plagiarism.service.ts` | `encoach_lms_api/controllers/plagiarism.py`
| ID | Requirement | Source |
|----|-------------|--------|
| FR-PLAG-01 | Enable/disable plagiarism check per assignment or exam | Client |
| FR-PLAG-02 | Automatic GPTZero analysis on submission | Client |
| FR-PLAG-03 | Downloadable plagiarism report (PDF) per submission | Client |
| FR-PLAG-04 | Configurable number of allowed submissions with plagiarism check | Client |
| FR-PLAG-05 | Teacher views plagiarism score and per-sentence analysis in grading interface | Client |
| FR-PLAG-06 | Aggregate plagiarism overview for assignment (flagged submissions count) | Client |
**API Endpoints:**
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/plagiarism/check` | Run plagiarism check on text/submission |
| `GET` | `/api/plagiarism/report/{submissionId}` | Get plagiarism report |
| `GET` | `/api/plagiarism/report/{submissionId}/download` | Download report as PDF |
### 19.3 Approval Workflows (Enhanced)
| ID | Requirement | Source |
|----|-------------|--------|
| FR-AWF-01 | List/filter workflows | Production |
| FR-AWF-02 | Create templates / add workflow | Production |
| FR-AWF-03 | **NEW:** AI Grading Assistant on workflow page | New frontend |
| FR-AWF-04 | **NEW:** Configurable approval stages with number of days per stage (shown as calendar) | Client |
| FR-AWF-05 | **NEW:** Auto-escalation -- if time passes, automatically move to next authority with highlighted reason | Client |
| FR-AWF-06 | **NEW:** Bypass option -- terminate approval flow with mandatory justification sent to final authority | Client |
| FR-AWF-07 | **NEW:** Comments saved through the approval process | Client |
| FR-AWF-08 | **NEW:** Status view of approval progress (first reviewer, rejected, final reviewer, etc.) | Client |
| FR-AWF-09 | **NEW:** Final authority can choose who to pass back the exam to | Client |
| FR-AWF-10 | **NEW:** Configurable email notifications per approval stage | Client |
| FR-AWF-11 | **NEW:** Approval applies to both exams and course materials | Client |
**Approval Stage Model:**
| Field | Type | Description |
|-------|------|-------------|
| `workflow_id` | Many2one | Parent workflow |
| `sequence` | Integer | Stage order |
| `approver_id` | Many2one | Approver user |
| `max_days` | Integer | Maximum days before auto-escalation |
| `notification_email` | Char | Email for notifications |
| `status` | Selection | `pending`, `approved`, `rejected`, `escalated`, `bypassed` |
| `comment` | Text | Reviewer comment |
| `acted_at` | Datetime | When action was taken |
---
# Part V -- AI Services
## 20. AI Services Catalog
> **Implementation:** `coaching.service.ts`, `analytics.service.ts`, `generation.service.ts`, `evaluations.service.ts`, `media.service.ts` | `encoach_ai/`, `encoach_ai_generation/`, `encoach_ai_grading/`, `encoach_ai_media/`, `encoach_adaptive_ai/`
| 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)
> **Implementation:** `users.service.ts` | `encoach_api/controllers/users.py` | `AdminUsers.tsx`
| 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)
> **Implementation:** `entities.service.ts` | `encoach_api/controllers/entities.py` | `AdminEntities.tsx`
| 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)
> **Implementation:** `classrooms.service.ts` | `encoach_api/controllers/classroom.py` | `AdminClassrooms.tsx`
| 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)
> **Implementation:** `assignments.service.ts` | `encoach_api/controllers/assignment.py` | `AdminAssignments.tsx`, `StudentAssignments.tsx`, `TeacherAssignments.tsx`
| 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) |
| FR-ASG-07 | **NEW:** Late submission handling -- configurable late submission date/time with penalty structure | Client |
| FR-ASG-08 | **NEW:** Extension requests -- students can request deadline extensions through the platform | Client |
| FR-ASG-09 | **NEW:** Submission tracking -- status flow (start date, extension granted, submitted, in review, graded) | Client |
| FR-ASG-10 | **NEW:** Configurable number of allowed submissions per assignment | Client |
| FR-ASG-11 | **NEW:** Revision history -- track all submission versions per student | Client |
| FR-ASG-12 | **NEW:** Reminder notifications -- configurable frequency, sent via email and system notification | Client |
### 25.2 Late Submission Policy
| Field | Type | Description |
|-------|------|-------------|
| `late_deadline` | Datetime | Final late submission cutoff |
| `penalty_type` | Selection | `none`, `percentage`, `fixed_deduction` |
| `penalty_value` | Float | Penalty amount (e.g., 10 = 10% or 10 points) |
| `max_submissions` | Integer | Maximum allowed submissions (0 = unlimited) |
| `allow_extensions` | Boolean | Whether students can request extensions |
### 25.3 Extension Request
| Field | Type | Description |
|-------|------|-------------|
| `student_id` | Many2one | Requesting student |
| `assignment_id` | Many2one | Target assignment |
| `reason` | Text | Justification |
| `requested_date` | Datetime | Requested new deadline |
| `status` | Selection | `pending`, `approved`, `rejected` |
| `approved_by` | Many2one | Approving teacher |
| `response_note` | Text | Teacher response |
---
## 26. Permission Management (Production Parity + Extension)
> **Implementation:** `entities.service.ts` (roles/permissions) | `encoach_api/controllers/roles.py` | `RolesPermissions.tsx`, `AuthorityMatrix.tsx`, `UserRoles.tsx`
| 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) |
### 26.2 Roles and Permissions CRUD (NEW -- Implemented)
The developer implemented a complete roles and permissions CRUD system beyond the original entity-scoped model.
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-ROLE-01 | List all roles with permission counts | `/admin/roles-permissions` | Admin |
| FR-ROLE-02 | Create role with name and description | `/admin/roles-permissions` | Admin |
| FR-ROLE-03 | Update role details | `/admin/roles-permissions` | Admin |
| FR-ROLE-04 | Delete role | `/admin/roles-permissions` | Admin |
| FR-ROLE-05 | Update role permissions (assign/remove permissions) | `/admin/roles-permissions` | Admin |
| FR-ROLE-06 | List all permissions | `/admin/roles-permissions` | Admin |
| FR-ROLE-07 | Create custom permission | `/admin/roles-permissions` | Admin |
| FR-ROLE-08 | Delete permission | `/admin/roles-permissions` | Admin |
**API Endpoints:**
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/roles` | List all roles |
| `POST` | `/api/roles` | Create role |
| `GET` | `/api/roles/{id}` | Get role detail |
| `PATCH` | `/api/roles/{id}` | Update role |
| `DELETE` | `/api/roles/{id}` | Delete role |
| `PATCH` | `/api/roles/{id}/permissions` | Update role permissions |
| `GET` | `/api/permissions` | List all permissions |
| `POST` | `/api/permissions` | Create permission |
| `DELETE` | `/api/permissions/{id}` | Delete permission |
### 26.3 User Role Assignment (NEW -- Implemented)
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-UROLE-01 | List users with their assigned roles | `/admin/user-roles` | Admin |
| FR-UROLE-02 | View roles for a specific user | `/admin/user-roles` | Admin |
| FR-UROLE-03 | Assign/remove roles for a user | `/admin/user-roles` | Admin |
| FR-UROLE-04 | Toggle individual role on/off for a user | `/admin/user-roles` | Admin |
**API Endpoints:**
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/users/with-roles` | List users with role details |
| `GET` | `/api/users/{id}/roles` | Get roles for a user |
| `PATCH` | `/api/users/{id}/roles` | Update user roles |
| `POST` | `/api/users/{id}/roles/toggle` | Toggle a single role |
### 26.4 Authority Matrix (NEW -- Implemented)
A visual matrix showing all roles vs. all permissions, allowing administrators to toggle permission assignments visually.
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-AUTH-01 | Display role-permission matrix (roles as columns, permissions as rows) | `/admin/authority-matrix` | Admin |
| FR-AUTH-02 | Toggle individual permission cells (grant/revoke) | `/admin/authority-matrix` | Admin |
| FR-AUTH-03 | View user-specific authority matrix | `/admin/authority-matrix` | Admin |
**API Endpoints:**
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/authority-matrix` | Get full role-permission matrix |
| `POST` | `/api/authority-matrix/toggle` | Toggle a permission cell |
| `GET` | `/api/user-authority-matrix` | Get user-level authority view |
---
# Part VII -- Support and Commercial
## 27. Ticketing System (Production Parity)
> **Implementation:** `tickets.service.ts` | `encoach_api/controllers/ticket.py` | `AdminTickets.tsx`
| 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
> **Implementation:** `subscriptions.service.ts` | `encoach_api/controllers/subscription.py` | `AdminPaymentRecord.tsx`, `Payment.tsx`
### 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
> **Implementation:** `training.service.ts` | `encoach_api/controllers/training.py` | `AdminTrainingVocabulary.tsx`, `AdminTrainingGrammar.tsx`
### 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
> **Implementation:** `academic.service.ts` | `encoach_lms_api/controllers/academic.py` | `AdminAcademicYears.tsx`
### 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
> **Implementation:** `academic.service.ts` | `encoach_lms_api/controllers/departments.py` | `AdminDepartments.tsx`
### 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
> **Implementation:** `admission.service.ts` | `encoach_lms_api/controllers/admissions.py` | `AdminAdmissionRegister.tsx`, `AdminAdmissions.tsx`
### 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
> **Implementation:** `institutional-exam.service.ts` | `encoach_lms_api/controllers/subject_registration.py` | `StudentSubjectRegistration.tsx`
### 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
> **Implementation:** `institutional-exam.service.ts` | `encoach_lms_api/controllers/inst_exams.py` | `AdminExamSessions.tsx`, `AdminMarksheets.tsx`
### 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
> **Implementation:** `institutional-exam.service.ts` | `encoach_lms_api/controllers/course_assignments.py` | `TeacherAssignments.tsx`, `StudentAssignments.tsx`
### 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 VIII-B -- OpenEduCat Enterprise Features
The following sections cover additional institutional features implemented by the developer beyond the original SRS. These features leverage OpenEduCat Enterprise modules and extend the platform with student lifecycle management, financial tracking, library services, and facility management.
---
## 36. Student Leave Management
> **Implementation:** `student-leave.service.ts` | `encoach_lms_api/controllers/student_leave.py` | `AdminStudentLeave.tsx`
### 36.1 Overview
Students submit leave requests with a type, date range, and justification. Administrators approve or reject requests. Leave types are configurable.
### 36.2 Data Models
**`op.student.leave.request`** (OpenEduCat Enterprise)
| Field | Type | Description |
|-------|------|-------------|
| `request_number` | Char | Auto-generated request number |
| `student_id` | Many2one | Requesting student |
| `leave_type` | Many2one | Leave type reference |
| `start_date` | Date | Leave start |
| `end_date` | Date | Leave end |
| `duration` | Float | Computed duration in days |
| `description` | Text | Justification |
| `state` | Selection | `draft`, `confirm`, `validate`, `approve`, `refuse`, `cancel` |
| `approve_date` | Date | Date of approval |
**`op.student.leave.type`**
| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Leave type name (e.g., Medical, Personal, Academic) |
### 36.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-SL-01 | List student leave requests with status filters | `/admin/student-leave` | Admin |
| FR-SL-02 | Create leave request (student, type, dates, description) | `/admin/student-leave` | Admin/Student |
| FR-SL-03 | Approve/reject leave request with state transition | `/admin/student-leave` | Admin |
| FR-SL-04 | Manage leave types (CRUD) | `/admin/student-leave` | Admin |
### 36.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/student-leaves` | List leave requests |
| `POST` | `/api/student-leaves` | Create leave request |
| `PATCH` | `/api/student-leaves/{id}` | Update leave request |
| `POST` | `/api/student-leaves/{id}/approve` | Approve request |
| `POST` | `/api/student-leaves/{id}/reject` | Reject request |
| `GET` | `/api/student-leave-types` | List leave types |
| `POST` | `/api/student-leave-types` | Create leave type |
---
## 37. Fees Management
> **Implementation:** `fees.service.ts` | `encoach_lms_api/controllers/fees.py` | `AdminFees.tsx`
### 37.1 Overview
Institutional fee plans track student financial obligations per course. The system tracks total, paid, and remaining amounts per student, linked to invoicing.
### 37.2 Data Models
**`op.fees.plan`** (OpenEduCat Enterprise)
| Field | Type | Description |
|-------|------|-------------|
| `student_id` | Many2one | Student |
| `course_id` | Many2one | Course |
| `total_amount` | Float | Total fee amount |
| `paid_amount` | Float | Amount paid to date |
| `remaining_amount` | Float | Computed remaining balance |
| `state` | Selection | Fee plan state |
**`op.student.fees.details`**
| Field | Type | Description |
|-------|------|-------------|
| `student_id` | Many2one | Student |
| `amount` | Float | Fee amount |
| `date` | Date | Fee date |
| `state` | Selection | Payment state |
| `invoice_state` | Selection | Invoice state |
| `product_name` | Char | Fee product name |
**`op.fees.terms`**
| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Term name |
| `no_days` | Integer | Number of days for payment |
| `line_ids` | One2many | Fee term lines |
### 37.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-FEES-01 | List fees plans with student and course details | `/admin/fees` | Admin |
| FR-FEES-02 | View individual student fees with payment history | `/admin/fees` | Admin |
| FR-FEES-03 | View fees terms configuration | `/admin/fees` | Admin |
### 37.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/fees-plans` | List fee plans |
| `GET` | `/api/fees-plans/{id}` | Get fee plan detail |
| `GET` | `/api/student-fees` | List student fee details |
| `GET` | `/api/fees-terms` | List fees terms |
---
## 38. Lessons Management
> **Implementation:** `lesson.service.ts` | `encoach_lms_api/controllers/lessons.py` | `AdminLessons.tsx`
### 38.1 Overview
Lessons represent individual teaching sessions within timetable sessions. They link subjects to specific timetable slots and track the topic covered.
### 38.2 Data Model
**`op.session.lesson`** (OpenEduCat Enterprise)
| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Lesson name |
| `lesson_topic` | Char | Topic covered |
| `course_id` | Many2one | Course |
| `batch_id` | Many2one | Batch |
| `subject_id` | Many2one | Subject |
| `session_id` | Many2one | Timetable session |
| `faculty_id` | Many2one | Teaching faculty |
| `start_datetime` | Datetime | Lesson start |
| `end_datetime` | Datetime | Lesson end |
### 38.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-LSN-01 | List lessons with subject and session details | `/admin/lessons` | Admin |
| FR-LSN-02 | Create lesson (name, topic, course, batch, subject, session, faculty, times) | `/admin/lessons` | Admin |
| FR-LSN-03 | Update/delete lessons | `/admin/lessons` | Admin |
### 38.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/lessons` | List lessons |
| `POST` | `/api/lessons` | Create lesson |
| `PATCH` | `/api/lessons/{id}` | Update lesson |
| `DELETE` | `/api/lessons/{id}` | Delete lesson |
---
## 39. Gradebook and Grading Assignments
> **Implementation:** `gradebook.service.ts` | `encoach_lms_api/controllers/gradebook.py` | `AdminGradebook.tsx`
### 39.1 Overview
The gradebook aggregates student marks across courses and academic years. Grading assignments define assessment items with marks and sequences. Gradebook lines show per-student, per-assignment results with percentages.
### 39.2 Data Models
**`op.gradebook`** (OpenEduCat Enterprise)
| Field | Type | Description |
|-------|------|-------------|
| `student_id` | Many2one | Student |
| `course_id` | Many2one | Course |
| `academic_year_id` | Many2one | Academic year |
| `line_ids` | One2many | Gradebook lines |
**`op.gradebook.line`**
| Field | Type | Description |
|-------|------|-------------|
| `gradebook_id` | Many2one | Parent gradebook |
| `student_name` | Char | Related student name |
| `assignment_name` | Char | Related assignment name |
| `marks` | Float | Marks obtained |
| `percentage` | Float | Computed percentage |
| `state` | Selection | Line state |
**`grading.assignment`** (extended)
| Field | Type | Description |
|-------|------|-------------|
| `sequence` | Char | Assignment sequence code |
| `name` | Char | Assignment name |
| `course_id` | Many2one | Course |
| `subject_id` | Many2one | Subject |
| `state` | Selection | Assignment state |
| `issued_date` | Date | Issue date |
### 39.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-GB-01 | List gradebooks filtered by course and academic year | `/admin/gradebook` | Admin |
| FR-GB-02 | View gradebook lines per student with marks and percentages | `/admin/gradebook` | Admin |
| FR-GB-03 | Create/update/delete grading assignments | `/admin/gradebook` | Admin |
### 39.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/gradebooks` | List gradebooks |
| `GET` | `/api/gradebook-lines` | List gradebook lines |
| `GET` | `/api/grading-assignments` | List grading assignments |
| `POST` | `/api/grading-assignments` | Create grading assignment |
| `PATCH` | `/api/grading-assignments/{id}` | Update grading assignment |
| `DELETE` | `/api/grading-assignments/{id}` | Delete grading assignment |
---
## 40. Student Progress Tracking
> **Implementation:** `student-progress.service.ts` | `encoach_lms_api/controllers/student_progress.py` | `AdminStudentProgress.tsx`
### 40.1 Overview
Aggregate view of student academic progression combining attendance, assignment completion, and marksheet results into a unified tracking interface.
### 40.2 Data Model
**`op.student.progression`** (OpenEduCat Enterprise)
| Field | Type | Description |
|-------|------|-------------|
| `student_id` | Many2one | Student |
| `total_attendance` | Float | Computed total attendance percentage |
| `total_assignment` | Float | Computed total assignment count/score |
| `total_marksheet_line` | Float | Computed total marksheet entries |
### 40.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-SP-01 | List student progress with attendance, assignment, and marksheet aggregates | `/admin/student-progress` | Admin |
| FR-SP-02 | Filter by course, batch, or individual student | `/admin/student-progress` | Admin |
### 40.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/student-progress` | List student progression records |
---
## 41. Library Management
> **Implementation:** `library.service.ts` | `encoach_lms_api/controllers/library.py` | `AdminLibrary.tsx`
### 41.1 Overview
Institutional library management supporting media cataloging, borrowing (movements), and library card issuance. Tracks media items (books, journals, CDs), their circulation, and student/faculty borrowing history.
### 41.2 Data Models
**`op.media`** (OpenEduCat Library)
| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Media title |
| `isbn` | Char | ISBN number |
| `author` | Char | Author name |
| `edition` | Char | Edition |
| `media_type` | Selection | Media type (book, journal, CD, etc.) |
**`op.media.movement`**
| Field | Type | Description |
|-------|------|-------------|
| `media_id` | Many2one | Media item |
| `student_id` | Many2one | Borrowing student |
| `faculty_id` | Many2one | Issuing faculty |
| `issued_date` | Date | Issue date |
| `return_date` | Date | Return date |
| `state` | Selection | Movement state (issued, returned, overdue) |
**`op.library.card`**
| Field | Type | Description |
|-------|------|-------------|
| `number` | Char | Card number |
| `student_id` | Many2one | Cardholder student |
| `faculty_id` | Many2one | Issuing faculty |
### 41.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-LIB-01 | Catalog media items with ISBN, author, edition | `/admin/library` | Admin |
| FR-LIB-02 | Track media movements (issue, return) | `/admin/library` | Admin |
| FR-LIB-03 | Issue and manage library cards | `/admin/library` | Admin |
| FR-LIB-04 | Delete media items | `/admin/library` | Admin |
### 41.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/library/media` | List media items |
| `POST` | `/api/library/media` | Create media item |
| `DELETE` | `/api/library/media/{id}` | Delete media item |
| `GET` | `/api/library/movements` | List movements |
| `POST` | `/api/library/movements` | Create movement (issue) |
| `PATCH` | `/api/library/movements/{id}` | Update movement |
| `POST` | `/api/library/movements/{id}/return` | Return media |
| `GET` | `/api/library/cards` | List library cards |
| `POST` | `/api/library/cards` | Create library card |
---
## 42. Activity Management
> **Implementation:** `activity.service.ts` | `encoach_lms_api/controllers/activities.py` | `AdminActivities.tsx`
### 42.1 Overview
Tracks extracurricular and academic activities per student. Activity types are configurable (sports, cultural, academic, volunteer, etc.).
### 42.2 Data Models
**`op.activity`** (OpenEduCat Activity)
| Field | Type | Description |
|-------|------|-------------|
| `student_id` | Many2one | Student |
| `type_id` | Many2one | Activity type |
| `date` | Date | Activity date |
| `description` | Text | Activity description |
**`op.activity.type`**
| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Type name |
### 42.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-ACT-01 | List student activities with type and date | `/admin/activities` | Admin |
| FR-ACT-02 | Create/update/delete activities | `/admin/activities` | Admin |
| FR-ACT-03 | Manage activity types (CRUD) | `/admin/activities` | Admin |
### 42.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/activities` | List activities |
| `POST` | `/api/activities` | Create activity |
| `PATCH` | `/api/activities/{id}` | Update activity |
| `DELETE` | `/api/activities/{id}` | Delete activity |
| `GET` | `/api/activity-types` | List activity types |
| `POST` | `/api/activity-types` | Create activity type |
| `DELETE` | `/api/activity-types/{id}` | Delete activity type |
---
## 43. Facility and Asset Management
> **Implementation:** `facility.service.ts` | `encoach_lms_api/controllers/facilities.py` | `AdminFacilities.tsx`
### 43.1 Overview
Manages institutional facilities (buildings, labs, rooms) and their associated assets (equipment, furniture). Facilities can be linked to classrooms and timetable sessions.
### 43.2 Data Models
**`op.facility`** (OpenEduCat Facility)
| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Facility name |
| `code` | Char | Facility code |
**`op.facility.line`** (Asset)
| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Asset name |
| `code` | Char | Asset code |
| `product_name` | Char | Product description |
### 43.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-FAC-01 | List facilities with codes | `/admin/facilities` | Admin |
| FR-FAC-02 | Create/update/delete facilities | `/admin/facilities` | Admin |
| FR-FAC-03 | List and manage assets within facilities | `/admin/facilities` | Admin |
### 43.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/facilities` | List facilities |
| `POST` | `/api/facilities` | Create facility |
| `PATCH` | `/api/facilities/{id}` | Update facility |
| `DELETE` | `/api/facilities/{id}` | Delete facility |
| `GET` | `/api/assets` | List assets |
| `POST` | `/api/assets` | Create asset |
| `DELETE` | `/api/assets/{id}` | Delete asset |
---
# Part IX -- Courseware and Content Delivery
This part covers the Moodle-style structured course delivery system: chapter-based content organization, material management, and AI-powered course content generation.
---
## 44. Course Chapters
> **Implementation:** `courseware.service.ts` | `encoach_lms_api/controllers/courseware.py` | `TeacherCourseChapters.tsx`, `StudentCourseChapterView.tsx`
### 44.1 Overview
Courses are divided into chapters (modules). Teachers create chapters with scheduled start dates, content materials, and lock/unlock controls. Students progress through chapters sequentially or as unlocked by the teacher.
### 44.2 Data Model (`encoach.course.chapter`)
| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Chapter title |
| `course_id` | Many2one | Parent course (`op.course`) |
| `sequence` | Integer | Display order |
| `description` | Text | Chapter description |
| `start_date` | Datetime | Scheduled start date |
| `end_date` | Datetime | Optional end date |
| `unlock_mode` | Selection | `auto_date` (unlock when start_date reached), `manual` (teacher clicks), `prerequisite` (previous chapter completed) |
| `is_unlocked` | Boolean | Current unlock status |
| `topic_id` | Many2one | Optional link to `encoach.topic` (bridges to adaptive engine) |
| `material_ids` | One2many | Chapter materials |
| `assignment_ids` | Many2many | Linked assignments |
| `exam_ids` | Many2many | Linked exams/quizzes |
| `active` | Boolean | Soft-delete flag |
### 44.3 Chapter Progress Model (`encoach.chapter.progress`)
| Field | Type | Description |
|-------|------|-------------|
| `student_id` | Many2one | Student |
| `chapter_id` | Many2one | Chapter |
| `status` | Selection | `not_started`, `in_progress`, `completed` |
| `started_at` | Datetime | When student first accessed |
| `completed_at` | Datetime | When marked complete |
| `materials_completed` | Integer | Count of materials viewed/downloaded |
| `materials_total` | Integer | Total materials in chapter |
### 44.4 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-CH-01 | Teacher creates chapters for a course with name, description, sequence | `/teacher/courses/:id/chapters` | Teacher |
| FR-CH-02 | Teacher sets chapter start date and unlock mode (auto/manual/prerequisite) | `/teacher/courses/:id/chapters` | Teacher |
| FR-CH-03 | Teacher reorders chapters via drag-and-drop | `/teacher/courses/:id/chapters` | Teacher |
| FR-CH-04 | Teacher manually unlocks/locks a chapter | `/teacher/courses/:id/chapters` | Teacher |
| FR-CH-05 | System auto-unlocks chapters when start_date is reached (cron job) | Backend | System |
| FR-CH-06 | Student sees unlocked chapters on course detail page | `/student/courses/:id` | Student |
| FR-CH-07 | Student views chapter content and materials | `/student/courses/:id/chapters/:chapterId` | Student |
| FR-CH-08 | System tracks per-student chapter progress | Backend | System |
| FR-CH-09 | Chapter completion notification sent to student | Backend | System |
| FR-CH-10 | Teacher views chapter progress per student | `/teacher/courses/:id/chapters` | Teacher |
### 44.5 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/courses/{courseId}/chapters` | List chapters for course |
| `POST` | `/api/courses/{courseId}/chapters` | Create chapter |
| `GET` | `/api/chapters/{id}` | Get chapter detail with materials |
| `PATCH` | `/api/chapters/{id}` | Update chapter |
| `DELETE` | `/api/chapters/{id}` | Delete chapter |
| `POST` | `/api/chapters/{id}/unlock` | Manually unlock chapter |
| `POST` | `/api/chapters/{id}/lock` | Manually lock chapter |
| `PATCH` | `/api/courses/{courseId}/chapters/reorder` | Reorder chapters |
| `GET` | `/api/chapters/{id}/progress` | Get student progress for chapter |
| `POST` | `/api/chapters/{id}/progress/complete` | Mark chapter as completed |
---
## 45. Chapter Materials
> **Implementation:** `courseware.service.ts` | `encoach_lms_api/controllers/courseware.py` | `TeacherCourseChapters.tsx`
### 45.1 Overview
Each chapter contains materials: uploaded files (PDFs, documents), videos, audio, images, hyperlinks, and articles. Teachers control download permissions per material.
### 45.2 Data Model (`encoach.chapter.material`)
| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Material title |
| `chapter_id` | Many2one | Parent chapter |
| `type` | Selection | `pdf`, `document`, `video`, `audio`, `image`, `link`, `article` |
| `file` | Binary | Uploaded file (for pdf, document, video, audio, image) |
| `url` | Char | External URL (for link, article, or external video) |
| `description` | Text | Material description |
| `sequence` | Integer | Display order |
| `allow_download` | Boolean | Whether students can download the file |
| `is_book` | Boolean | Whether this material is a course book (multi-book support) |
| `book_chapters` | Text (JSON) | Book chapter structure (if following original book chapters) |
| `active` | Boolean | Soft-delete flag |
### 45.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-MAT-01 | Teacher uploads materials (PDF, Word, video, audio, images) per chapter | `/teacher/courses/:id/chapters/:chapterId` | Teacher |
| FR-MAT-02 | Teacher adds external links, articles, hyperlinks | `/teacher/courses/:id/chapters/:chapterId` | Teacher |
| FR-MAT-03 | Teacher uploads books with chapter structure (follow original or custom) | `/teacher/courses/:id/chapters/:chapterId` | Teacher |
| FR-MAT-04 | Teacher sets download enable/disable per material | `/teacher/courses/:id/chapters/:chapterId` | Teacher |
| FR-MAT-05 | Teacher uploads teaching aids (video, audio, pictures, hyperlinks) | `/teacher/courses/:id/chapters/:chapterId` | Teacher |
| FR-MAT-06 | Student views materials for unlocked chapters | `/student/courses/:id/chapters/:chapterId` | Student |
| FR-MAT-07 | Student downloads materials if download is enabled | `/student/courses/:id/chapters/:chapterId` | Student |
| FR-MAT-08 | System tracks which materials a student has viewed/downloaded | Backend | System |
### 45.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/chapters/{chapterId}/materials` | List materials |
| `POST` | `/api/chapters/{chapterId}/materials` | Upload material (multipart) |
| `PATCH` | `/api/materials/{id}` | Update material metadata |
| `DELETE` | `/api/materials/{id}` | Delete material |
| `GET` | `/api/materials/{id}/download` | Download material file |
| `POST` | `/api/materials/{id}/viewed` | Mark material as viewed by student |
| `PATCH` | `/api/chapters/{chapterId}/materials/reorder` | Reorder materials |
---
## 46. AI Workbench for Course Content
> **Implementation:** `courseware.service.ts` | `encoach_lms_api/controllers/courseware.py` | `TeacherAIWorkbench.tsx`
### 46.1 Overview
Teachers use the AI Workbench to generate course content automatically. The AI generates chapters, materials, exercises, and grading rubrics based on high-level requirements input by the teacher.
### 46.2 AI Workbench Flow
1. Teacher inputs: topic name, objectives, complexity level, target audience
2. AI generates: chapter structure with learning outcomes, reading content, exercises, multimedia suggestions
3. Teacher reviews generated content
4. Teacher can: modify, regenerate specific sections, add additional context
5. Teacher approves and publishes (follows approval workflow if configured)
6. AI can suggest additional materials based on selected student performance profiles
### 46.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-WB-01 | Teacher opens AI Workbench from course page | `/teacher/courses/:id/workbench` | Teacher |
| FR-WB-02 | Teacher inputs high-level requirements (topic, objectives, complexity) | `/teacher/courses/:id/workbench` | Teacher |
| FR-WB-03 | AI generates course outline with chapters and learning outcomes | `/teacher/courses/:id/workbench` | Teacher |
| FR-WB-04 | AI generates reading content, exercises, and multimedia for each chapter | `/teacher/courses/:id/workbench` | Teacher |
| FR-WB-05 | AI generates grading rubrics based on assignment/exam complexity | `/teacher/courses/:id/workbench` | Teacher |
| FR-WB-06 | Teacher reviews and modifies AI-generated content | `/teacher/courses/:id/workbench` | Teacher |
| FR-WB-07 | Teacher can prompt AI to regenerate specific sections | `/teacher/courses/:id/workbench` | Teacher |
| FR-WB-08 | Teacher selects student profiles for AI to suggest additional materials based on performance | `/teacher/courses/:id/workbench` | Teacher |
| FR-WB-09 | Generated content follows approval workflow before publishing | Backend | System |
### 46.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/workbench/generate-outline` | Generate course outline from requirements |
| `POST` | `/api/workbench/generate-chapter` | Generate content for a specific chapter |
| `POST` | `/api/workbench/generate-rubric` | Generate grading rubric |
| `POST` | `/api/workbench/regenerate` | Regenerate a specific section |
| `POST` | `/api/workbench/suggest-materials` | AI suggests materials based on student profiles |
| `POST` | `/api/workbench/publish` | Publish generated content to course chapters |
---
# Part X -- Communication
## 47. Discussion Boards
> **Implementation:** `communication.service.ts` | `encoach_lms_api/controllers/communication.py` | `StudentDiscussions.tsx`, `TeacherDiscussions.tsx`
### 47.1 Overview
Per-class discussion boards enable student-to-student and student-to-teacher communication. Discussion boards can be attached to courses, chapters, or assignments.
### 47.2 Data Models
**`encoach.discussion.board`**
| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Board title |
| `course_id` | Many2one | Associated course |
| `batch_id` | Many2one | Associated batch (optional) |
| `chapter_id` | Many2one | Associated chapter (optional) |
| `assignment_id` | Many2one | Associated assignment (optional) |
| `is_enabled` | Boolean | Whether teacher has enabled discussions |
| `allow_student_posts` | Boolean | Whether students can create new threads |
| `post_count` | Integer | Computed post count |
**`encoach.discussion.post`**
| Field | Type | Description |
|-------|------|-------------|
| `board_id` | Many2one | Parent board |
| `parent_id` | Many2one | Parent post (for replies, nested threads) |
| `author_id` | Many2one | Author user |
| `title` | Char | Post title (for root posts) |
| `content` | Text | Post content (supports markdown) |
| `attachment_ids` | Many2many | File attachments |
| `is_pinned` | Boolean | Pinned by teacher |
| `is_resolved` | Boolean | Marked as resolved (for Q&A) |
| `created_at` | Datetime | Post time |
### 47.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-DISC-01 | Teacher enables/disables discussion board per course or chapter | `/teacher/courses/:id/discussions` | Teacher |
| FR-DISC-02 | Students create discussion threads | `/student/discussions` | Student |
| FR-DISC-03 | Students and teachers reply to threads (nested replies) | `/student/discussions`, `/teacher/courses/:id/discussions` | Both |
| FR-DISC-04 | Teacher pins important posts | `/teacher/courses/:id/discussions` | Teacher |
| FR-DISC-05 | Teacher marks posts as resolved | `/teacher/courses/:id/discussions` | Teacher |
| FR-DISC-06 | Students view other participants within the same class | `/student/discussions` | Student |
| FR-DISC-07 | File attachments on posts | Both pages | Both |
### 47.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/discussion-boards` | List boards (filter: course_id, batch_id) |
| `POST` | `/api/discussion-boards` | Create board |
| `PATCH` | `/api/discussion-boards/{id}` | Update board settings |
| `GET` | `/api/discussion-boards/{id}/posts` | List posts for board (paginated) |
| `POST` | `/api/discussion-boards/{id}/posts` | Create post/reply |
| `PATCH` | `/api/posts/{id}` | Update post |
| `DELETE` | `/api/posts/{id}` | Delete post |
| `POST` | `/api/posts/{id}/pin` | Pin/unpin post |
| `POST` | `/api/posts/{id}/resolve` | Mark as resolved |
---
## 48. Announcements
> **Implementation:** `communication.service.ts` | `encoach_lms_api/controllers/communication.py` | `StudentAnnouncements.tsx`, `TeacherAnnouncements.tsx`
### 48.1 Overview
Teachers broadcast announcements to classes. System-wide announcements can be created by administrators.
### 48.2 Data Model (`encoach.announcement`)
| Field | Type | Description |
|-------|------|-------------|
| `title` | Char | Announcement title |
| `content` | Text | Announcement body (supports markdown) |
| `author_id` | Many2one | Author |
| `course_id` | Many2one | Target course (null = system-wide) |
| `batch_id` | Many2one | Target batch (null = all batches in course) |
| `priority` | Selection | `normal`, `important`, `urgent` |
| `is_published` | Boolean | Published status |
| `published_at` | Datetime | Publish time |
| `expires_at` | Datetime | Expiry time (optional) |
| `send_email` | Boolean | Also send via email |
| `attachment_ids` | Many2many | File attachments |
### 48.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-ANN-01 | Teacher creates announcement for class/batch | `/teacher/announcements` | Teacher |
| FR-ANN-02 | Teacher sends announcement via platform and/or email | `/teacher/announcements` | Teacher |
| FR-ANN-03 | Admin creates system-wide announcements | `/admin/announcements` | Admin |
| FR-ANN-04 | Students view announcements on dashboard and dedicated page | `/student/announcements` | Student |
| FR-ANN-05 | Priority-based display (urgent announcements highlighted) | All dashboards | All |
### 48.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/announcements` | List announcements (filter: course_id, priority) |
| `POST` | `/api/announcements` | Create announcement |
| `PATCH` | `/api/announcements/{id}` | Update announcement |
| `DELETE` | `/api/announcements/{id}` | Delete announcement |
| `POST` | `/api/announcements/{id}/publish` | Publish announcement |
---
## 49. Messaging
> **Implementation:** `communication.service.ts` | `encoach_lms_api/controllers/communication.py` | `StudentMessages.tsx`, `TeacherMessages.tsx`
### 49.1 Overview
Direct messaging between platform users. Teachers can message students individually. Students can message other students within the same class (if allowed). Platform can send emails through linked accounts.
### 49.2 Data Model (`encoach.message`)
| Field | Type | Description |
|-------|------|-------------|
| `sender_id` | Many2one | Sender user |
| `recipient_id` | Many2one | Recipient user |
| `subject` | Char | Message subject |
| `content` | Text | Message body |
| `is_read` | Boolean | Read status |
| `read_at` | Datetime | When read |
| `attachment_ids` | Many2many | File attachments |
| `send_email_copy` | Boolean | Also send copy via email |
| `created_at` | Datetime | Sent time |
### 49.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-MSG-01 | Users send direct messages to other users | `/student/messages`, `/teacher/messages` | All |
| FR-MSG-02 | Inbox with read/unread filtering | `/student/messages` | All |
| FR-MSG-03 | Option to send email copy through the platform | Both pages | All |
| FR-MSG-04 | File attachments on messages | Both pages | All |
| FR-MSG-05 | Students see other participants within same class | `/student/messages` | Student |
### 49.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/messages` | List messages (inbox, filter: unread) |
| `GET` | `/api/messages/sent` | List sent messages |
| `POST` | `/api/messages` | Send message |
| `GET` | `/api/messages/{id}` | Get message detail (marks as read) |
| `DELETE` | `/api/messages/{id}` | Delete message |
| `GET` | `/api/messages/unread-count` | Get unread message count |
---
# Part XI -- Notifications and FAQ
## 50. Notification Engine
> **Implementation:** `notification.service.ts` | `encoach_lms_api/controllers/notification.py` | `AdminNotificationRules.tsx`
### 50.1 Overview
Centralized notification system supporting both in-app and email notifications. Notifications are triggered by system events (deadlines, chapter unlocks, result releases, announcements) and can be configured by teachers and admins.
### 50.2 Data Models
**`encoach.notification`**
| Field | Type | Description |
|-------|------|-------------|
| `user_id` | Many2one | Recipient user |
| `title` | Char | Notification title |
| `message` | Text | Notification body |
| `type` | Selection | `deadline`, `chapter_unlock`, `result_release`, `announcement`, `assignment`, `exam`, `message`, `system` |
| `action_url` | Char | URL to redirect to when clicked |
| `is_read` | Boolean | Read status |
| `read_at` | Datetime | When read |
| `channel` | Selection | `in_app`, `email`, `both` |
| `created_at` | Datetime | Created time |
**`encoach.notification.rule`**
| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Rule name |
| `event_type` | Selection | `assignment_due`, `exam_due`, `chapter_unlock`, `result_release`, `submission_graded`, `extension_response` |
| `days_before` | Integer | Days before event to send notification |
| `frequency` | Selection | `once`, `daily`, `custom` |
| `custom_intervals` | Text (JSON) | Custom reminder intervals (e.g., [7, 3, 1] days before) |
| `channel` | Selection | `in_app`, `email`, `both` |
| `entity_id` | Many2one | Entity scope |
| `active` | Boolean | Active flag |
**`encoach.notification.preferences`**
| Field | Type | Description |
|-------|------|-------------|
| `user_id` | Many2one | User |
| `email_enabled` | Boolean | Receive email notifications |
| `assignment_alerts` | Boolean | Assignment deadline alerts |
| `exam_alerts` | Boolean | Exam alerts |
| `chapter_alerts` | Boolean | Chapter unlock alerts |
| `announcement_alerts` | Boolean | Announcement alerts |
| `message_alerts` | Boolean | New message alerts |
### 50.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-NOT-01 | In-app notification bell with unread count (existing NotificationDropdown enhanced) | All layouts | All |
| FR-NOT-02 | Email notifications for configured events | Backend | System |
| FR-NOT-03 | Admin configures notification rules (event type, timing, frequency) | `/admin/notification-rules` | Admin |
| FR-NOT-04 | Teacher sets reminder frequency for assignments and exams | Assignment/exam creation forms | Teacher |
| FR-NOT-05 | Students receive deadline alerts, chapter unlock alerts, result release alerts | Dashboard | Student |
| FR-NOT-06 | Users configure personal notification preferences | Profile pages | All |
| FR-NOT-07 | Notification action button redirects to relevant page | All layouts | All |
### 50.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/notifications` | List notifications (paginated, filter: type, is_read) |
| `POST` | `/api/notifications/{id}/read` | Mark as read |
| `POST` | `/api/notifications/read-all` | Mark all as read |
| `GET` | `/api/notifications/unread-count` | Get unread count |
| `GET` | `/api/notification-rules` | List rules |
| `POST` | `/api/notification-rules` | Create rule |
| `PATCH` | `/api/notification-rules/{id}` | Update rule |
| `DELETE` | `/api/notification-rules/{id}` | Delete rule |
| `GET` | `/api/notification-preferences` | Get user preferences |
| `PATCH` | `/api/notification-preferences` | Update user preferences |
---
## 51. FAQ System
> **Implementation:** `faq.service.ts` | `encoach_lms_api/controllers/faq.py` | `AdminFAQ.tsx`, `FAQ.tsx` (public)
### 51.1 Overview
Interactive FAQ system editable by super admin. FAQ items are organized by categories and filtered by target audience (student, entity, or both). Supports text, images, and video content.
### 51.2 Data Models
**`encoach.faq.category`**
| Field | Type | Description |
|-------|------|-------------|
| `name` | Char | Category name |
| `sequence` | Integer | Display order |
| `icon` | Char | Icon identifier |
| `audience` | Selection | `student`, `entity`, `both` |
| `active` | Boolean | Active flag |
**`encoach.faq.item`**
| Field | Type | Description |
|-------|------|-------------|
| `question` | Char | Question text |
| `answer` | Text | Answer (supports markdown, embedded images/video) |
| `category_id` | Many2one | Parent category |
| `audience` | Selection | `student`, `entity`, `both` |
| `image` | Binary | Optional image |
| `video_url` | Char | Optional video URL |
| `sequence` | Integer | Display order |
| `active` | Boolean | Active flag |
### 51.3 Functional Requirements
| ID | Requirement | Route | Role |
|----|-------------|-------|------|
| FR-FAQ-01 | Super admin manages FAQ categories and items | `/admin/faq` | Admin |
| FR-FAQ-02 | Admin adds text, images, and video to FAQ answers | `/admin/faq` | Admin |
| FR-FAQ-03 | Admin sets audience filter per category/item (student, entity, both) | `/admin/faq` | Admin |
| FR-FAQ-04 | Students and entity users view FAQs filtered by their role | `/faq` | All |
| FR-FAQ-05 | Search bar to find FAQ items by keyword | `/faq` | All |
| FR-FAQ-06 | Interactive accordion-style display (click question to expand answer) | `/faq` | All |
### 51.4 API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/faq/categories` | List categories (filter: audience) |
| `POST` | `/api/faq/categories` | Create category |
| `PATCH` | `/api/faq/categories/{id}` | Update category |
| `DELETE` | `/api/faq/categories/{id}` | Delete category |
| `GET` | `/api/faq/items` | List items (filter: category_id, audience, search) |
| `POST` | `/api/faq/items` | Create item |
| `PATCH` | `/api/faq/items/{id}` | Update item |
| `DELETE` | `/api/faq/items/{id}` | Delete item |
---
# Part XII -- Technical Specifications
## 52. Data Models
### 52.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 |
### 52.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` |
### 52.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 |
### 52.4 New Models (Branding)
| Model | Module | Purpose |
|-------|--------|---------|
| `encoach.branding` | `encoach_branding` | Tenant branding configuration (logo, colors, fonts) |
### 52.5 New Models (OpenEduCat Enterprise -- Beyond SRS)
| Model | Module | Purpose | Key Fields |
|-------|--------|---------|------------|
| `op.student.leave.request` | `openeducat_student_leave_enterprise` | Student leave requests | `request_number`, `student_id`, `leave_type`, `start_date`, `end_date`, `duration`, `description`, `state`, `approve_date` |
| `op.student.leave.type` | `openeducat_student_leave_enterprise` | Leave type definitions | `name` |
| `op.fees.plan` | `openeducat_fees` | Student fee plans | `student_id`, `course_id`, `total_amount`, `paid_amount`, `remaining_amount`, `state` |
| `op.student.fees.details` | `openeducat_fees` | Fee payment details | `student_id`, `amount`, `date`, `state`, `invoice_state`, `product_name` |
| `op.fees.terms` | `openeducat_fees` | Fee payment terms | `name`, `no_days`, `line_ids` |
| `op.session.lesson` | `openeducat_lesson` | Lesson sessions | `name`, `lesson_topic`, `course_id`, `batch_id`, `subject_id`, `session_id`, `faculty_id`, `start_datetime`, `end_datetime` |
| `op.gradebook` | `openeducat_grading` | Student gradebooks | `student_id`, `course_id`, `academic_year_id`, `line_ids` |
| `op.gradebook.line` | `openeducat_grading` | Gradebook entries | `gradebook_id`, `marks`, `percentage`, `state` |
| `op.student.progression` | `openeducat_student_progress_enterprise` | Aggregate progress tracking | `student_id`, `total_attendance`, `total_assignment`, `total_marksheet_line` |
| `op.media` | `openeducat_library` | Library media catalog | `name`, `isbn`, `author`, `edition`, `media_type` |
| `op.media.movement` | `openeducat_library` | Library circulation | `media_id`, `student_id`, `faculty_id`, `issued_date`, `return_date`, `state` |
| `op.library.card` | `openeducat_library` | Library cards | `number`, `student_id`, `faculty_id` |
| `op.activity` | `openeducat_activity` | Student activities | `student_id`, `type_id`, `date`, `description` |
| `op.activity.type` | `openeducat_activity` | Activity type definitions | `name` |
| `op.facility` | `openeducat_facility` | Institutional facilities | `name`, `code` |
| `op.facility.line` | `openeducat_facility` | Facility assets | `name`, `code`, `product_name` |
### 52.6 Frontend Type Definitions (29 files)
The frontend defines TypeScript interfaces matching all backend models:
| Type File | Key Interfaces |
|-----------|---------------|
| `common.ts` | `PaginatedResponse`, `ApiResponse`, `PaginationParams` |
| `auth.ts` | `User`, `UserRole`, `LoginRequest`, `LoginResponse` |
| `entity.ts` | `Entity`, `EntityRole`, `RolePermission` |
| `exam.ts` | `Exam`, `Rubric`, `ExamStructure` |
| `assignment.ts` | `Assignment`, `AssignmentCreateRequest` |
| `classroom.ts` | `Classroom`, `ClassroomMember` |
| `stats.ts` | `ExamSession`, `Stat`, `Evaluation` |
| `subscription.ts` | `Package`, `Payment`, `Discount` |
| `ticket.ts` | `Ticket` |
| `training.ts` | `Training`, `Tip`, `Walkthrough` |
| `taxonomy.ts` | `Subject`, `Domain`, `Topic`, `LearningObjective`, `TaxonomyTree` |
| `adaptive.ts` | `Proficiency`, `LearningPlan`, `DiagnosticSession`, `TopicContent` |
| `lms.ts` | `Course`, `Batch`, `Timetable`, `Attendance`, `Grade` |
| `ai.ts` | `Chat`, `Insight`, `Alert`, `AiGeneration`, `AiGrading` |
| `academic.ts` | `AcademicYear`, `Term`, `Department` |
| `admission.ts` | `Register`, `Admission` |
| `institutional-exam.ts` | `ExamSession`, `Marksheet`, `Submission` |
| `courseware.ts` | `Chapter`, `Material`, `Workbench` |
| `communication.ts` | `DiscussionBoard`, `Post`, `Announcement`, `Message` |
| `notification.ts` | `Notification`, `NotificationRule`, `Preferences` |
| `faq.ts` | `FaqCategory`, `FaqItem` |
| `student-leave.ts` | `StudentLeaveRequest`, `StudentLeaveType` |
| `fees.ts` | `FeesPlan`, `StudentFeesDetail`, `FeesTerms` |
| `lesson.ts` | `Lesson`, `LessonCreateRequest` |
| `gradebook.ts` | `Gradebook`, `GradebookLine`, `GradingAssignment` |
| `student-progress.ts` | `StudentProgression` |
| `library.ts` | `MediaItem`, `MediaMovement`, `LibraryCard` |
| `activity.ts` | `Activity`, `ActivityType` |
| `facility.ts` | `Facility`, `Asset` |
---
## 53. REST API Specification
### 53.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 |
### 53.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 |
### 53.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 |
### 53.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 |
### 53.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 |
---
### 53.6 New Endpoints (Courseware, Communication, Notifications, FAQ, 60+)
| Group | Method | Path | Description |
|-------|--------|------|-------------|
| **Chapters** | `GET` | `/api/courses/{courseId}/chapters` | List chapters |
| | `POST` | `/api/courses/{courseId}/chapters` | Create chapter |
| | `GET` | `/api/chapters/{id}` | Chapter detail |
| | `PATCH` | `/api/chapters/{id}` | Update chapter |
| | `DELETE` | `/api/chapters/{id}` | Delete chapter |
| | `POST` | `/api/chapters/{id}/unlock` | Unlock chapter |
| | `POST` | `/api/chapters/{id}/lock` | Lock chapter |
| | `PATCH` | `/api/courses/{courseId}/chapters/reorder` | Reorder |
| | `GET` | `/api/chapters/{id}/progress` | Progress |
| | `POST` | `/api/chapters/{id}/progress/complete` | Complete |
| **Materials** | `GET` | `/api/chapters/{chapterId}/materials` | List |
| | `POST` | `/api/chapters/{chapterId}/materials` | Upload |
| | `PATCH` | `/api/materials/{id}` | Update |
| | `DELETE` | `/api/materials/{id}` | Delete |
| | `GET` | `/api/materials/{id}/download` | Download |
| | `POST` | `/api/materials/{id}/viewed` | Mark viewed |
| **Workbench** | `POST` | `/api/workbench/generate-outline` | Generate outline |
| | `POST` | `/api/workbench/generate-chapter` | Generate chapter |
| | `POST` | `/api/workbench/generate-rubric` | Generate rubric |
| | `POST` | `/api/workbench/regenerate` | Regenerate section |
| | `POST` | `/api/workbench/suggest-materials` | Suggest materials |
| | `POST` | `/api/workbench/publish` | Publish content |
| **Discussions** | `GET/POST` | `/api/discussion-boards` | List/create boards |
| | `PATCH` | `/api/discussion-boards/{id}` | Update board |
| | `GET/POST` | `/api/discussion-boards/{id}/posts` | List/create posts |
| | `PATCH/DELETE` | `/api/posts/{id}` | Update/delete post |
| | `POST` | `/api/posts/{id}/pin` | Pin post |
| | `POST` | `/api/posts/{id}/resolve` | Resolve post |
| **Announcements** | `GET/POST` | `/api/announcements` | List/create |
| | `PATCH/DELETE` | `/api/announcements/{id}` | Update/delete |
| | `POST` | `/api/announcements/{id}/publish` | Publish |
| **Messages** | `GET` | `/api/messages` | Inbox |
| | `GET` | `/api/messages/sent` | Sent |
| | `POST` | `/api/messages` | Send |
| | `GET` | `/api/messages/{id}` | Detail |
| | `DELETE` | `/api/messages/{id}` | Delete |
| | `GET` | `/api/messages/unread-count` | Unread count |
| **Notifications** | `GET` | `/api/notifications` | List |
| | `POST` | `/api/notifications/{id}/read` | Mark read |
| | `POST` | `/api/notifications/read-all` | Read all |
| | `GET` | `/api/notifications/unread-count` | Count |
| | `GET/POST` | `/api/notification-rules` | Rules |
| | `PATCH/DELETE` | `/api/notification-rules/{id}` | Rule CRUD |
| | `GET/PATCH` | `/api/notification-preferences` | User prefs |
| **FAQ** | `GET/POST` | `/api/faq/categories` | Categories |
| | `PATCH/DELETE` | `/api/faq/categories/{id}` | Category CRUD |
| | `GET/POST` | `/api/faq/items` | Items |
| | `PATCH/DELETE` | `/api/faq/items/{id}` | Item CRUD |
| **Plagiarism** | `POST` | `/api/plagiarism/check` | Check text |
| | `GET` | `/api/plagiarism/report/{submissionId}` | Get report |
| | `GET` | `/api/plagiarism/report/{submissionId}/download` | Download PDF |
| **Exam Access** | `POST` | `/api/exam/{id}/generate-link` | Generate access link |
| | `GET` | `/api/exam/access/{token}` | Access via link |
| | `POST` | `/api/exam/official-login` | Official exam login |
### 53.7 New Endpoints (OpenEduCat Enterprise Features, 40+)
| Group | Method | Path | Description |
|-------|--------|------|-------------|
| **Student Leave** | `GET` | `/api/student-leaves` | List leave requests |
| | `POST` | `/api/student-leaves` | Create leave request |
| | `PATCH` | `/api/student-leaves/{id}` | Update leave |
| | `POST` | `/api/student-leaves/{id}/approve` | Approve |
| | `POST` | `/api/student-leaves/{id}/reject` | Reject |
| | `GET/POST` | `/api/student-leave-types` | Leave types |
| **Fees** | `GET` | `/api/fees-plans` | List fee plans |
| | `GET` | `/api/fees-plans/{id}` | Fee plan detail |
| | `GET` | `/api/student-fees` | Student fee details |
| | `GET` | `/api/fees-terms` | Fee terms |
| **Lessons** | `GET/POST` | `/api/lessons` | List/create lessons |
| | `PATCH/DELETE` | `/api/lessons/{id}` | Update/delete |
| **Gradebook** | `GET` | `/api/gradebooks` | List gradebooks |
| | `GET` | `/api/gradebook-lines` | Gradebook lines |
| | `GET/POST` | `/api/grading-assignments` | Grading assignments |
| | `PATCH/DELETE` | `/api/grading-assignments/{id}` | CRUD |
| **Student Progress** | `GET` | `/api/student-progress` | Progression records |
| **Library** | `GET/POST` | `/api/library/media` | Media items |
| | `DELETE` | `/api/library/media/{id}` | Delete media |
| | `GET/POST` | `/api/library/movements` | Movements |
| | `PATCH` | `/api/library/movements/{id}` | Update movement |
| | `POST` | `/api/library/movements/{id}/return` | Return media |
| | `GET/POST` | `/api/library/cards` | Library cards |
| **Activities** | `GET/POST` | `/api/activities` | Activities |
| | `PATCH/DELETE` | `/api/activities/{id}` | CRUD |
| | `GET/POST` | `/api/activity-types` | Activity types |
| | `DELETE` | `/api/activity-types/{id}` | Delete type |
| **Facilities** | `GET/POST` | `/api/facilities` | Facilities |
| | `PATCH/DELETE` | `/api/facilities/{id}` | CRUD |
| | `GET/POST` | `/api/assets` | Assets |
| | `DELETE` | `/api/assets/{id}` | Delete asset |
| **Roles** | `GET/POST` | `/api/roles` | Roles |
| | `GET/PATCH/DELETE` | `/api/roles/{id}` | Role CRUD |
| | `PATCH` | `/api/roles/{id}/permissions` | Update permissions |
| | `GET/POST` | `/api/permissions` | Permissions |
| | `DELETE` | `/api/permissions/{id}` | Delete permission |
| | `GET` | `/api/users/with-roles` | Users with roles |
| | `GET/PATCH` | `/api/users/{id}/roles` | User roles |
| | `POST` | `/api/users/{id}/roles/toggle` | Toggle role |
| | `GET` | `/api/authority-matrix` | Authority matrix |
| | `POST` | `/api/authority-matrix/toggle` | Toggle cell |
| | `GET` | `/api/user-authority-matrix` | User authority |
---
## 54. Frontend Page Inventory
### 54.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` |
### 54.2 Student Pages (18+)
| 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` | -- |
| `/student/courses/:id/chapters/:chapterId` | **NEW:** Chapter View | `/api/chapters/{id}`, `/api/chapters/{chapterId}/materials` | -- |
| `/student/discussions` | **NEW:** Discussion Board | `/api/discussion-boards`, `/api/discussion-boards/{id}/posts` | -- |
| `/student/announcements` | **NEW:** Announcements | `/api/announcements` | -- |
| `/student/messages` | **NEW:** Messages | `/api/messages`, `/api/messages/unread-count` | -- |
| `/student/journey` | **NEW:** Student Journey | `/api/analytics/student`, `/api/proficiency` | -- |
### 54.3 Teacher Pages (15+)
| 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` | -- |
| `/teacher/courses/:id/chapters` | **NEW:** Course Chapters | `/api/courses/{courseId}/chapters` | -- |
| `/teacher/courses/:id/chapters/:chapterId` | **NEW:** Chapter Detail | `/api/chapters/{id}`, `/api/chapters/{chapterId}/materials` | -- |
| `/teacher/courses/:id/workbench` | **NEW:** AI Workbench | `/api/workbench/*` | AiCreationAssistant |
| `/teacher/courses/:id/discussions` | **NEW:** Discussion Board | `/api/discussion-boards`, `/api/discussion-boards/{id}/posts` | -- |
| `/teacher/announcements` | **NEW:** Announcements | `/api/announcements` | -- |
### 54.4 Public Pages (4+)
| Route | Page | Key APIs | AI Components |
|-------|------|----------|---------------|
| `/apply` | **NEW:** Admission Application | `/api/admissions`, `/api/admission-registers` | -- |
| `/apply/status` | **NEW:** Application Status | `/api/admissions/{id}` | -- |
| `/exam/access/{token}` | **NEW:** Official Exam Access (Link) | `/api/exam/access/{token}` | -- |
| `/exam/official/{code}` | **NEW:** Official Exam Access (Landing) | `/api/exam/official-login` | -- |
| `/exam/login/{examId}` | **NEW:** Official Exam Login | `/api/exam/official-login` | -- |
| `/faq` | **NEW:** FAQ | `/api/faq/categories`, `/api/faq/items` | -- |
### 54.5 Admin Pages (53 -- Verified)
| 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` | Taxonomy Manager | `/api/subjects`, `/api/domains`, `/api/topics` | -- |
| `/admin/resources` | Resource Manager | `/api/resources`, `/api/analytics/content-gaps` | -- |
| `/admin/adaptive-analytics` | 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` | Academic Year Manager | `/api/academic-years`, `/api/academic-terms` | -- |
| `/admin/departments` | Department Manager | `/api/departments` | -- |
| `/admin/admissions` | Admission List | `/api/admissions` | -- |
| `/admin/admissions/:id` | Admission Detail | `/api/admissions/{id}` | -- |
| `/admin/admission-register` | Admission Register | `/api/admission-registers` | -- |
| `/admin/exam-sessions` | Institutional Exam Sessions | `/api/inst-exam-sessions`, `/api/inst-exams` | -- |
| `/admin/marksheets` | Marksheet Manager | `/api/marksheets`, `/api/result-templates`, `/api/grade-config` | -- |
| `/admin/faq` | FAQ Manager | `/api/faq/categories`, `/api/faq/items` | -- |
| `/admin/notification-rules` | Notification Rules | `/api/notification-rules` | -- |
| `/admin/approval-config` | Approval Workflow Config | `/api/approval-workflows` | -- |
| `/admin/student-leave` | **BEYOND SRS:** Student Leave Management | `/api/student-leaves`, `/api/student-leave-types` | -- |
| `/admin/fees` | **BEYOND SRS:** Fees Management | `/api/fees-plans`, `/api/student-fees`, `/api/fees-terms` | -- |
| `/admin/lessons` | **BEYOND SRS:** Lessons Management | `/api/lessons` | -- |
| `/admin/gradebook` | **BEYOND SRS:** Gradebook | `/api/gradebooks`, `/api/gradebook-lines`, `/api/grading-assignments` | -- |
| `/admin/student-progress` | **BEYOND SRS:** Student Progress | `/api/student-progress` | -- |
| `/admin/library` | **BEYOND SRS:** Library Management | `/api/library/media`, `/api/library/movements`, `/api/library/cards` | -- |
| `/admin/activities` | **BEYOND SRS:** Activity Management | `/api/activities`, `/api/activity-types` | -- |
| `/admin/facilities` | **BEYOND SRS:** Facility Management | `/api/facilities`, `/api/assets` | -- |
| `/admin/roles-permissions` | **BEYOND SRS:** Roles & Permissions CRUD | `/api/roles`, `/api/permissions` | -- |
| `/admin/user-roles` | **BEYOND SRS:** User Role Assignment | `/api/users/with-roles` | -- |
| `/admin/authority-matrix` | **BEYOND SRS:** Authority Matrix | `/api/authority-matrix` | -- |
---
## 55. 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 (Verified Against Backend v2)
The following module inventory reflects the actual deployed modules in `encoach_backend_new_v2`:
**Custom EnCoach Modules (27):**
| # | Module | Status | Description |
|---|--------|--------|-------------|
| 1 | `encoach_core` | Deployed | Users, entities, roles, permissions, codes, invites |
| 2 | `encoach_ai` | Deployed | OpenAI service, constants, blacklist, token counting |
| 3 | `encoach_ai_media` | Deployed | TTS (Polly), STT (Whisper), ELAI avatars |
| 4 | `encoach_ai_generation` | Deployed | Exam content generation (multi-subject) |
| 5 | `encoach_ai_grading` | Deployed | Writing/speaking grading (multi-subject rubrics) |
| 6 | `encoach_exam` | Deployed | Exam model with `subject_id`, `topic_ids` |
| 7 | `encoach_assignment` | Deployed | Exam assignments |
| 8 | `encoach_classroom` | Deployed | Classroom groups |
| 9 | `encoach_stats` | Deployed | Sessions and statistics with `topic_id`, `subject_id` |
| 10 | `encoach_training` | Deployed | Training tips and walkthroughs |
| 11 | `encoach_subscription` | Deployed | Packages, payments, discounts |
| 12 | `encoach_registration` | Deployed | User registration and batch import |
| 13 | `encoach_ticket` | Deployed | Support tickets |
| 14 | `encoach_api` | Deployed | REST API controllers (~120 routes: auth, users, entities, roles, exams, assignments, classrooms, storage, stats, subscriptions, tickets, approvals, training, generation, AI analytics) |
| 15 | `encoach_taxonomy` | Deployed | Subject, domain, topic, learning objective models |
| 16 | `encoach_resources` | Deployed | Learning resource library (~7 routes) |
| 17 | `encoach_adaptive` | Deployed | Proficiency, learning plans, progress tracking, content cache |
| 18 | `encoach_adaptive_api` | Deployed | REST controllers for adaptive learning (~41 routes: taxonomy, diagnostic, proficiency, learning plans, content, coaching) |
| 19 | `encoach_adaptive_ai` | Deployed | AI services for diagnostics, plans, coaching, content |
| 20 | `encoach_lms_api` | Deployed | REST API bridge for OpenEduCat + enterprise models (~209 routes) |
| 21 | `encoach_sis` | Deployed | UTAS SIS integration (sync, mapping) |
| 22 | `encoach_branding` | Deployed | Whitelabeling configuration |
| 23 | `encoach_courseware` | Deployed | Course chapters, chapter materials, chapter progress, AI workbench |
| 24 | `encoach_communication` | Deployed | Discussion boards, posts, announcements, messaging |
| 25 | `encoach_notification` | Deployed | Notification engine, notification rules, reminders, preferences |
| 26 | `encoach_faq` | Deployed | FAQ categories and items, role-filtered |
| 27 | `encoach_approval` | Deployed | Approval workflows, stages, requests |
**OpenEduCat Community Modules (14):**
| # | Module | Status | Description |
|---|--------|--------|-------------|
| 1 | `openeducat_core` | Deployed | `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` |
| 2 | `openeducat_timetable` | Deployed | `op.session`, `op.timing` |
| 3 | `openeducat_attendance` | Deployed | `op.attendance.register`, `op.attendance.sheet`, `op.attendance.line`, `op.attendance.type` |
| 4 | `openeducat_classroom` | Deployed | `op.classroom` (physical rooms) |
| 5 | `openeducat_exam` | Deployed | `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` |
| 6 | `openeducat_assignment` | Deployed | `op.assignment`, `op.assignment.sub.line`, `grading.assignment`, `grading.assignment.type` |
| 7 | `openeducat_admission` | Deployed | `op.admission`, `op.admission.register` |
| 8 | `openeducat_facility` | Deployed | `op.facility`, `op.facility.line` |
| 9 | `openeducat_fees` | Deployed | `op.fees.plan`, `op.student.fees.details`, `op.fees.terms` |
| 10 | `openeducat_library` | Deployed | `op.media`, `op.media.movement`, `op.library.card` |
| 11 | `openeducat_activity` | Deployed | `op.activity`, `op.activity.type` |
| 12 | `openeducat_parent` | Deployed | Parent-student relationship management |
| 13 | `openeducat_erp` | Deployed | OpenEduCat ERP connector (meta-module) |
| 14 | `theme_web_openeducat` | Deployed | OpenEduCat web theme |
**Total: 27 custom EnCoach + 14 OpenEduCat = 41 modules**
---
## Appendix B: Implementation Status
All items have been implemented and deployed to staging. The table below records the original priority assignments.
| Priority | Components | Status |
|----------|-----------|--------|
| **P0** | Auth, core user management, taxonomy models, resource model | **DONE** |
| **P1** | Diagnostic engine, proficiency profile, learning plan generation | **DONE** |
| **P1** | Exam engine with multi-subject support | **DONE** |
| **P2** | OpenEduCat porting (v17→v19), LMS API bridge, course/batch/timetable/attendance | **DONE** |
| **P2** | Academic years/terms, departments, admission workflow | **DONE** |
| **P2** | Content delivery (hybrid), practice questions, mastery quizzes | **DONE** |
| **P2** | AI components wiring (all 15 frontend components to real backend) | **DONE** |
| **P3** | AI coaching (hints, explanations, study suggestions) | **DONE** |
| **P3** | Spaced repetition, analytics dashboards | **DONE** |
| **P3** | Institutional exam sessions, marksheets, subject registration | **DONE** |
| **P3** | Course assignment submissions (file upload, grading) | **DONE** |
| **P2** | Courseware module (chapters, materials, progress tracking) | **DONE** |
| **P2** | Communication module (discussions, announcements, messaging) | **DONE** |
| **P3** | Notification engine (rules, email integration, reminders) | **DONE** |
| **P3** | Enhanced approval workflows (timed stages, escalation, bypass) | **DONE** |
| **P3** | Plagiarism detection (GPTZero integration) | **DONE** |
| **P3** | Official exam access modes (link, landing page, separate login) | **DONE** |
| **P4** | FAQ system (admin-managed, role-filtered) | **DONE** |
| **P4** | AI Workbench for course content generation | **DONE** |
| **P3** | SIS integration, whitelabeling | **DONE** |
| **P4** | Content gap detection, FAISS tips per subject, batch optimizer | **DONE** |
| **P4** | Payment system, subscription management | **DONE** |
| **--** | **BEYOND SRS:** Student leave management | **DONE** |
| **--** | **BEYOND SRS:** Fees management | **DONE** |
| **--** | **BEYOND SRS:** Lessons management | **DONE** |
| **--** | **BEYOND SRS:** Gradebook and grading assignments | **DONE** |
| **--** | **BEYOND SRS:** Student progress tracking | **DONE** |
| **--** | **BEYOND SRS:** Library management | **DONE** |
| **--** | **BEYOND SRS:** Activity management | **DONE** |
| **--** | **BEYOND SRS:** Facility and asset management | **DONE** |
| **--** | **BEYOND SRS:** Roles CRUD, user role assignment, authority matrix | **DONE** |
## Appendix C: API Route Summary (Verified)
| Controller Package | Route Count | Scope |
|-------------------|-------------|-------|
| `encoach_api` | ~120 | Auth, users, entities, roles, exams, assignments, classrooms, storage, stats, subscriptions, tickets, approvals, training, generation, AI analytics |
| `encoach_lms_api` | ~209 | Courses, students, teachers, batches, timetable, attendance, grades, departments, academic, admissions, subject registration, institutional exams, course assignments, student leave, fees, lessons, gradebook, student progress, library, activities, facilities, notifications, FAQ, courseware, plagiarism, communication, classrooms |
| `encoach_adaptive_api` | ~41 | Taxonomy (subjects, domains, topics), diagnostic, proficiency, learning plans, content, coaching |
| `encoach_resources` | ~7 | Learning resources (CRUD, download, complete, rate) |
| **Total** | **~377** | |
## Appendix D: Frontend File Summary (Verified)
| Category | Count | Location |
|----------|-------|----------|
| **Root pages** | 28 | `src/pages/*.tsx` |
| **Admin pages** | 33 | `src/pages/admin/*.tsx` |
| **Student pages** | 19 | `src/pages/student/*.tsx` |
| **Teacher pages** | 14 | `src/pages/teacher/*.tsx` |
| **Total pages** | **93** | |
| **Service modules** | 37 | `src/services/*.service.ts` |
| **Type definition files** | 29 | `src/types/*.ts` |
| **Query hook modules** | 21 | `src/hooks/queries/use*.ts` |
| **AI components** | 14 | `src/components/ai/*.tsx` |
---
*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`, `ENCOACH_UNIFIED_SRS.md` v1.0) are superseded by this document for new development.*
Reference in New Issue View Git Blame Copy Permalink