Files

Yamen Ahmad f1c4953a63 feat(v3): restructure project + add complete frontend

- Restructure: move backend from new_project/ to backend/
- Add full React/TypeScript frontend (37 pages, 17 services, 16 type defs, 11 query hooks)
- Add docs/ with SRS specs, user stories, and workflow documentation
- Update .gitignore for new directory layout

Workflows implemented:
  WF1 User Signup, WF2 Placement Test, WF3 Exam Configuration,
  WF4 General English Exam, WF5 Course Generation,
  WF6 Entity Student Onboarding, AI Course Generation,
  Adaptive Learning Engine UI, White-Label Branding, Score Release

Made-with: Cursor

2026-04-10 17:26:42 +04:00

153 KiB

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.

Part I -- Platform Foundation

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

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

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

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

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

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

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

Part VIII -- Institutional LMS (OpenEduCat) 30. Academic Year and Term Management 31. Department Management 32. Admission and Enrollment 33. Subject Registration 34. Institutional Exam Sessions 35. Assignment File Submissions

Part VIII-B -- OpenEduCat Enterprise Features 36. Student Leave Management 37. Fees Management 38. Lessons Management 39. Gradebook and Grading Assignments 40. Student Progress Tracking 41. Library Management 42. Activity Management 43. Facility and Asset Management

Part IX -- Courseware and Content Delivery 44. Course Chapters 45. Chapter Materials 46. AI Workbench for Course Content

Part X -- Communication 47. Discussion Boards 48. Announcements 49. Messaging

Part XI -- Notifications and FAQ 50. Notification Engine 51. FAQ System

Part XII -- Technical Specifications 52. Data Models 53. REST API Specification 54. Frontend Page Inventory 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

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

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

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

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

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

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

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

2.2 Technology Stack

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

2.3 Multi-Tenant Model

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

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

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

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

3. User Roles and Multi-Tenancy

3.1 User Types

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

3.2 Entity-Scoped Permissions

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

4. Authentication and Authorization

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

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

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

Student sidebar: Dashboard, Subjects, Courses, 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

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

9.3 Plan Adjustments

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

10. Hybrid Content Delivery

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

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

10.2 Resource Types

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

10.3 AI Coaching

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

11. Progress Tracking and Mastery

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
FR-ASG-08	NEW: Extension requests -- students can request deadline extensions through the platform
FR-ASG-09	NEW: Submission tracking -- status flow (start date, extension granted, submitted, in review, graded)
FR-ASG-10	NEW: Configurable number of allowed submissions per assignment
FR-ASG-11	NEW: Revision history -- track all submission versions per student
FR-ASG-12	NEW: Reminder notifications -- configurable frequency, sent via email and system notification

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

Teacher inputs: topic name, objectives, complexity level, target audience
AI generates: chapter structure with learning outcomes, reading content, exercises, multimedia suggestions
Teacher reviews generated content
Teacher can: modify, regenerate specific sections, add additional context
Teacher approves and publishes (follows approval workflow if configured)
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.

153 KiB Raw Blame History

EnCoach Unified Platform -- Software Requirements Specification

Implementation Status

Table of Contents

Part I -- Platform Foundation

1. Introduction

1.1 Purpose

1.2 Scope

1.3 Definitions

1.4 Key Architectural Decisions

2. System Architecture

2.1 Architecture Overview

2.2 Technology Stack

2.3 Multi-Tenant Model

3. User Roles and Multi-Tenancy

3.1 User Types

3.2 Entity-Scoped Permissions

4. Authentication and Authorization

4.1 Authentication

4.2 Authorization -- Entity Role Permissions

4.3 Global Permissions

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

5. Global UI Shell

5.1 Navbar

5.2 Sidebar Navigation

5.3 Breadcrumbs

Part II -- Universal Subject Engine

6. Subject Taxonomy

6.1 Hierarchy

6.2 IELTS / English Taxonomy

6.3 Mathematics Taxonomy

6.4 Information Technology Taxonomy

6.5 Taxonomy Management

7. Diagnostic Assessment

7.1 Purpose

7.2 Adaptive Algorithm

7.3 Question Types per Subject

7.4 Integration with Existing Exam Model

8. Proficiency Profile

8.1 Mastery Levels

8.2 Profile Updates

9. Learning Plan Generation

9.1 Two Modes

9.2 Algorithm

9.3 Plan Adjustments

10. Hybrid Content Delivery

10.1 Content Resolution Order

10.2 Resource Types

10.3 AI Coaching

11. Progress Tracking and Mastery

11.1 Mastery Quiz

11.2 Spaced Repetition

11.3 Analytics

Part III -- LMS Module

12. Course Management

12.1 Overview

12.2 Functional Requirements

12.3 Course Data Model

13. Batch and Enrollment

14. Timetable and Attendance

15. Gradebook and Reports

Part IV -- Exam Engine

16. Exam Management

16.1 Exam CRUD (Production Parity)

16.2 Official Exam Access (NEW)

16.4 Rubrics (Production Parity)

16.5 Exam Structures (Production Parity)

17. AI Content Generation

17.1 Generation per Subject

17.2 Generation Workflow

18. Exam Delivery

18.1 Delivery Modes

18.2 Media Integration

19. AI Grading

19.1 Grading per Subject

19.2 Plagiarism Detection (NEW -- Implemented)

19.3 Approval Workflows (Enhanced)

Part V -- AI Services

20. AI Services Catalog

21. AI Integration in Frontend

153 KiB

Raw Blame History