encoach_frontend_new_v3/docs/ENCOACH_ODOO19_BACKEND_SRS.md

EnCoach Platform — Odoo 19 Backend SRS

Version: 3.0
Date: March 11, 2026
Status: Implemented — Staging Verified
Supersedes: ODOO_BACKEND_SRS_v3.md, ODOO_MIGRATION_SRS_v2.md, ODOO_MIGRATION_SRS.md
Frontend Reference: ENCOACH_UNIFIED_SRS.md (v2.0)
Purpose: Complete backend specification for the EnCoach Adaptive Learning Platform on Odoo 19. All modules, models, and REST API endpoints have been implemented and deployed to staging.

Implementation Status

Artifact	Location
Backend Repository	https://git.albousalh.com/devops/encoach_backend_new_v2.git (branch: main)
Frontend Repository	https://git.albousalh.com/devops/encoach_frontend_new_v2.git (branch: main)
Staging Backend (Odoo 19)	http://5.189.151.117:8069
Staging Frontend	http://5.189.151.117:3000
Custom EnCoach Modules	27 modules in new_project/custom_addons/
OpenEduCat Modules	14 community modules in new_project/openeducat_erp-19.0/
Total API Routes	~377 REST endpoints across 4 controller packages
Deployment	Docker Compose (Odoo 19 + PostgreSQL 16)

Note: The developer implemented all features in this SRS plus additional OpenEduCat Enterprise features documented in Section 34 (Beyond-SRS Features).

---

Table of Contents

1. Introduction
2. Architecture Overview
3. OpenEduCat Integration Strategy
4. Module Inventory
5. Authentication and User Management
6. Entity and Permission System
7. LMS Core (OpenEduCat Bridge)
8. Academic Year, Term, and Department
9. Admission and Enrollment
10. Subject Registration
11. Exam Engine (EnCoach AI)
12. Institutional Exams (OpenEduCat)
13. Assignment System
14. Course Assignment Submissions (OpenEduCat)
15. Classroom and Group Management
16. Subject Taxonomy Engine
17. Adaptive Learning Engine
18. Learning Resources
19. AI Services
20. Training Content
21. Analytics and Statistics
22. Subscription and Payments
23. Support Tickets
24. File Storage
25. Approval Workflows (Enhanced)
26. Courseware and Content Delivery
27. Communication System
28. Notification Engine
29. FAQ System
30. Plagiarism Detection
31. Official Exam Access
32. Non-Functional Requirements
33. Implementation Priority
34. Beyond-SRS Features (Implemented)

---

1. Introduction

1.1 Scope

This document specifies the complete Odoo 19 backend for the EnCoach Adaptive Learning Platform. The backend serves a React SPA frontend via REST API. All endpoints use JSON request/response with JWT authentication (except explicitly public endpoints).

1.2 Frontend Contract

The React frontend has 29 API service modules that define the exact endpoints the backend must implement. This SRS documents every endpoint, its expected request/response shape, and the underlying Odoo models.

1.3 Key Principles

• OpenEduCat First: All traditional LMS features (courses, batches, students, faculty, timetable, attendance, exams, assignments, admissions) use OpenEduCat community modules ported to Odoo 19.
• EnCoach Extensions: Custom modules extend OpenEduCat models with fields the platform needs (e.g., description, image, max_capacity on op.course).
• REST API Layer: All data is exposed via REST controllers in encoach_api and encoach_lms_api modules. The frontend never uses Odoo's web client or XML-RPC.
• AI Services: AI functionality (GPT, Whisper, Polly, ELAI, GPTZero, FAISS) is encapsulated in dedicated encoach_ai_* modules with API endpoints.

---

2. Architecture Overview

React SPA (Vite + TypeScript)
     │
     ▼ REST API (JSON + JWT)
┌─────────────────────────────────┐
│         Odoo 19 Server          │
│                                 │
│  ┌──────────┐  ┌──────────────┐ │
│  │ encoach_ │  │  OpenEduCat  │ │
│  │ modules  │  │  (ported v19)│ │
│  └──────────┘  └──────────────┘ │
│         │              │        │
│         ▼              ▼        │
│      PostgreSQL 16              │
└─────────────────────────────────┘
     │
     ▼ External Services
  OpenAI API │ AWS Polly │ ELAI │ GPTZero

2.1 Technology Stack

Layer	Technology
Framework	Odoo 19 Community Edition
Language	Python 3.12+
Database	PostgreSQL 16
LMS Foundation	OpenEduCat (ported from v17 to v19)
AI/ML	OpenAI GPT-4o, Whisper (local), AWS Polly, Sentence Transformers, FAISS
Authentication	JWT (PyJWT)
File Storage	Odoo ir.attachment + optional S3
Deployment	Docker, Docker Compose

---

3. OpenEduCat Integration Strategy

3.1 Modules to Port (v17 → v19)

Module	Models	Porting Notes
openeducat_core	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	Core dependency for all other modules
openeducat_timetable	op.session, op.timing	Depends on openeducat_core
openeducat_attendance	op.attendance.register, op.attendance.sheet, op.attendance.line, op.attendance.type	Depends on openeducat_core, openeducat_timetable
openeducat_classroom	op.classroom	Depends on openeducat_facility
openeducat_facility	op.facility, op.facility.line	Dependency of classroom
openeducat_exam	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	Depends on openeducat_core
openeducat_assignment	op.assignment, op.assignment.sub.line, grading.assignment, grading.assignment.type	Depends on openeducat_core
openeducat_admission	op.admission, op.admission.register	Depends on openeducat_core

3.2 Model Extensions (via encoach_lms_api)

The encoach_lms_api module uses _inherit to add fields missing from OpenEduCat but required by the frontend:

Model	Added Fields
op.course	description (Text), image (Binary), max_capacity (Integer), status (Selection: draft/active/archived), department_id (Many2one to op.department)
op.batch	max_students (Integer), status (Selection: draft/active/completed)
op.student	enrollment_date (Date), status (Selection: active/inactive/graduated/suspended)
op.faculty	department_id (Many2one to op.department), specialization (Char)
op.subject	credits (Float), department_id (Many2one to op.department)

3.3 Serialization

All OpenEduCat models need to_api_dict() methods on the encoach_lms_api inheriting models that convert records to JSON-serializable dictionaries with snake_case keys. Many2one fields are serialized as {field}_id (integer) and {field}_name (string).

---

4. Module Inventory

#	Module	Type	Description
1	openeducat_core	OpenEduCat (port v19)	Course, batch, student, faculty, subject, department, academic year/term
2	openeducat_timetable	OpenEduCat (port v19)	Timetable sessions and timings
3	openeducat_attendance	OpenEduCat (port v19)	Attendance sheets, lines, registers
4	openeducat_classroom	OpenEduCat (port v19)	Physical classrooms
5	openeducat_facility	OpenEduCat (port v19)	Facility management
6	openeducat_exam	OpenEduCat (port v19)	Institutional exam sessions, marksheets, grading
7	openeducat_assignment	OpenEduCat (port v19)	Course assignments and submissions
8	openeducat_admission	OpenEduCat (port v19)	Admission registers and applications
9	encoach_core	Custom	encoach.user extensions on res.users, entities, roles, permissions, codes, invites
10	encoach_api	Custom	REST API controllers for auth, users, entities, permissions, exams, assignments, classrooms, tickets, subscriptions, stats, storage, approvals
11	encoach_lms_api	Custom	REST API bridge for OpenEduCat models (courses, batches, timetable, attendance, grades, academic years, departments, admissions, subject registration, institutional exams, marksheets, course assignments)
12	encoach_ai	Custom	OpenAI service wrapper, token counting, blacklist, system parameter management
13	encoach_ai_media	Custom	TTS (AWS Polly), STT (Whisper), ELAI avatar video generation
14	encoach_ai_generation	Custom	AI exam content generation for all subjects
15	encoach_ai_grading	Custom	AI grading for writing, speaking, math, IT
16	encoach_exam	Custom	encoach.exam model for AI-powered exams
17	encoach_assignment	Custom	encoach.assignment model (exam-wrapper assignments)
18	encoach_evaluation	Custom	Evaluation job tracking
19	encoach_stats	Custom	Session tracking and statistics
20	encoach_training	Custom	Training tips, walkthroughs, FAISS embeddings
21	encoach_classroom	Custom	encoach.classroom.group for virtual classrooms
22	encoach_subscription	Custom	Packages, payments, discounts, Stripe/PayPal/Paymob
23	encoach_registration	Custom	User registration and batch import
24	encoach_ticket	Custom	Support tickets
25	encoach_taxonomy	Custom	Subject, domain, topic, learning objective models
26	encoach_resources	Custom	Learning resource library
27	encoach_adaptive	Custom	Proficiency tracking, learning plans, progress, content cache
28	encoach_adaptive_api	Custom	REST controllers for adaptive learning
29	encoach_adaptive_ai	Custom	AI services for diagnostics, plan generation, coaching, content generation
30	encoach_sis	Custom	UTAS SIS integration (sync, mapping)
31	encoach_branding	Custom	Whitelabeling configuration
32	encoach_courseware	Custom	Course chapters, chapter materials, chapter progress tracking, AI workbench for content generation
33	encoach_communication	Custom	Discussion boards, threaded posts, announcements, direct messaging
34	encoach_notification	Custom	Notification engine, configurable rules, email/in-app delivery, user preferences
35	encoach_faq	Custom	FAQ categories and items, role-filtered, searchable

Original plan: 8 OpenEduCat + 27 custom = 35 modules

4.2 Additional Modules (Implemented Beyond SRS)

The developer added 6 more OpenEduCat community modules:

#	Module	Type	Description
36	openeducat_fees	OpenEduCat (port v19)	Fee plans, student fees, fee terms
37	openeducat_library	OpenEduCat (port v19)	Media catalog, movements, library cards
38	openeducat_activity	OpenEduCat (port v19)	Student activities, activity types
39	openeducat_parent	OpenEduCat (port v19)	Parent-student relationships
40	openeducat_erp	OpenEduCat (port v19)	ERP connector meta-module
41	theme_web_openeducat	OpenEduCat (port v19)	Web theme

Deployed total: 14 OpenEduCat + 27 custom = 41 modules

---

5. Authentication and User Management

5.1 Authentication Model

JWT-based authentication. Tokens are issued on login and validated on every API request.

5.2 User Model

Extends res.users with encoach.user mixin:

Field	Type	Description
user_type	Selection	student, teacher, admin, corporate, mastercorporate, agent, developer
is_verified	Boolean	Email verification status
entity_ids	Many2many	Associated entities
phone	Char	Phone number
birth_date	Date	Date of birth
gender	Selection	m, f, o
op_student_id	Many2one	Link to op.student if user_type is student
op_faculty_id	Many2one	Link to op.faculty if user_type is teacher

5.3 API Endpoints

Method	Path	Auth	Description
POST	/api/login	Public	Authenticate user, return JWT + user object
POST	/api/logout	JWT	Invalidate token
GET	/api/user	JWT	Get current authenticated user
POST	/api/reset/sendVerification	Public	Send password reset / verification email
GET	/api/users/list	JWT	Paginated user list with filters (type, entity_id, page, size)
GET	/api/users/{id}	JWT	Get user by ID
PATCH	/api/users/update	JWT	Update user (id in body)
POST	/api/users/create	JWT	Create user
POST	/api/batch_users	JWT	Batch create users from CSV/JSON
GET	/api/users/export	JWT	Export users as CSV blob

5.4 Login Response Shape

{
  "token": "eyJ...",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "user_type": "admin",
    "is_verified": true,
    "entities": [
      { "id": 1, "name": "UTAS", "logo": "..." }
    ]
  }
}

---

6. Entity and Permission System

6.1 Entity Model (encoach.entity)

Field	Type	Description
name	Char	Entity name
code	Char	Unique code
type	Selection	corporate, university, freelance
logo	Binary	Entity logo
active	Boolean	Active status
user_ids	Many2many	Members
role_ids	One2many	Custom roles

6.2 Role and Permission Models

encoach.role

Field	Type	Description
name	Char	Role name
entity_id	Many2one	Parent entity
permission_ids	Many2many	Assigned permissions

encoach.permission

77+ entity-scoped permissions (e.g., view_students, edit_exam, view_payment_record, manage_entities).

6.3 API Endpoints

Method	Path	Auth	Description
GET	/api/entities	JWT	Paginated entities
GET	/api/entities/{id}	JWT	Entity detail
POST	/api/entities	JWT	Create entity
PATCH	/api/entities/{id}	JWT	Update entity
DELETE	/api/entities/{id}	JWT	Delete entity
GET	/api/entities/{entityId}/roles	JWT	Roles for entity
POST	/api/entities/{entityId}/roles	JWT	Create role
PATCH	/api/roles/{roleId}/permissions	JWT	Update role permissions
GET	/api/permissions	JWT	List permissions (filter by entity_id)

---

7. LMS Core (OpenEduCat Bridge)

7.1 Course API

Backed by op.course (extended via _inherit in encoach_lms_api).

Method	Path	Auth	Description
GET	/api/courses	JWT	Paginated courses (filter: status, department_id)
GET	/api/courses/{id}	JWT	Course detail with subjects, batches
POST	/api/courses	JWT	Create course
PATCH	/api/courses/{id}	JWT	Update course
DELETE	/api/courses/{id}	JWT	Delete course
POST	/api/courses/ai-generate	JWT	AI-generate course outline (calls OpenAI)

Course Response Shape:

{
  "id": 1,
  "name": "IELTS Preparation",
  "code": "IELTS-101",
  "description": "Comprehensive IELTS preparation course",
  "department_id": 1,
  "department_name": "English",
  "max_capacity": 30,
  "status": "active",
  "subject_ids": [1, 2, 3],
  "subject_names": ["Reading", "Writing", "Listening"],
  "batch_count": 2,
  "student_count": 45,
  "image": "base64..."
}

7.2 Batch API

Backed by op.batch (extended).

Method	Path	Auth	Description
GET	/api/batches	JWT	Paginated batches (filter: course_id, status)
GET	/api/batches/{id}	JWT	Batch detail with student list
POST	/api/batches	JWT	Create batch
PATCH	/api/batches/{id}	JWT	Update batch
DELETE	/api/batches/{id}	JWT	Delete batch

7.3 Timetable API

Backed by op.session and op.timing.

Method	Path	Auth	Description
GET	/api/timetable	JWT	Sessions (filter: course_id, batch_id, faculty_id, start_date, end_date)
POST	/api/timetable	JWT	Create timetable session

Session Response Shape:

{
  "id": 1,
  "name": "IELTS Reading - Week 1",
  "course_id": 1,
  "course_name": "IELTS Preparation",
  "batch_id": 1,
  "batch_name": "Batch A",
  "faculty_id": 5,
  "faculty_name": "Dr. Smith",
  "subject_id": 1,
  "subject_name": "Reading",
  "classroom_id": 3,
  "classroom_name": "Room 101",
  "start_datetime": "2026-03-15T09:00:00",
  "end_datetime": "2026-03-15T10:30:00",
  "day": "Monday"
}

7.4 Attendance API

Backed by op.attendance.sheet and op.attendance.line.

Method	Path	Auth	Description
GET	/api/attendance	JWT	Attendance records (filter: course_id, batch_id, student_id, date_from, date_to)
POST	/api/attendance	JWT	Record attendance (batch of student attendance lines)

Attendance Record Request:

{
  "session_id": 1,
  "attendance_date": "2026-03-15",
  "lines": [
    { "student_id": 1, "present": true },
    { "student_id": 2, "present": false, "remark": "Sick leave" }
  ]
}

7.5 Grades API

Method	Path	Auth	Description
GET	/api/grades	JWT	Grade records (filter: student_id, course_id, batch_id)

---

8. Academic Year, Term, and Department

8.1 Academic Year and Term

Backed by op.academic.year and op.academic.term (OpenEduCat core).

Method	Path	Auth	Description
GET	/api/academic-years	JWT	List academic years with terms
GET	/api/academic-years/{id}	JWT	Year detail with terms
POST	/api/academic-years	JWT	Create academic year
PATCH	/api/academic-years/{id}	JWT	Update year
DELETE	/api/academic-years/{id}	JWT	Delete year
POST	/api/academic-years/{id}/generate-terms	JWT	Auto-generate terms from term_structure
GET	/api/academic-terms	JWT	List terms (filter: year_id)
POST	/api/academic-terms	JWT	Create term
PATCH	/api/academic-terms/{id}	JWT	Update term
DELETE	/api/academic-terms/{id}	JWT	Delete term

Generate Terms Logic:

Given term_structure on the academic year, compute term dates:

• two_sem: 2 terms splitting the year in half
• two_sem_qua: 2 semesters, each with 2 quarters (4 terms total)
• three_sem: 3 trimesters
• four_Quarter: 4 quarters
• final_year: single term spanning the full year

8.2 Department

Backed by op.department (OpenEduCat core).

Method	Path	Auth	Description
GET	/api/departments	JWT	List departments
POST	/api/departments	JWT	Create department
PATCH	/api/departments/{id}	JWT	Update department
DELETE	/api/departments/{id}	JWT	Delete department

Department Response:

{
  "id": 1,
  "name": "Department of Mathematics",
  "code": "MATH",
  "parent_id": null,
  "parent_name": null,
  "course_count": 5,
  "faculty_count": 12
}

---

9. Admission and Enrollment

9.1 Admission Register

Backed by op.admission.register (OpenEduCat).

Method	Path	Auth	Description
GET	/api/admission-registers	JWT	List registers
POST	/api/admission-registers	JWT	Create register
PATCH	/api/admission-registers/{id}	JWT	Update register
POST	/api/admission-registers/{id}/confirm	JWT	Confirm register (opens enrollment)
POST	/api/admission-registers/{id}/close	JWT	Close register

9.2 Admission

Backed by op.admission (OpenEduCat).

Method	Path	Auth	Description
GET	/api/admissions	JWT	List admissions (filter: state, register_id, course_id, page, size)
GET	/api/admissions/{id}	JWT	Admission detail
POST	/api/admissions	Public*	Submit admission application
POST	/api/admissions/{id}/submit	JWT	Submit for review
POST	/api/admissions/{id}/confirm	JWT	Confirm admission
POST	/api/admissions/{id}/admit	JWT	Admit applicant
POST	/api/admissions/{id}/reject	JWT	Reject admission

*Note: POST /api/admissions is public when submitted via the /apply page. Backend should allow unauthenticated submission when the register allows public applications.

9.3 Admit Action Logic

When an admission is admitted (/admit):

1. Create op.student record from admission data
2. Create res.users record with user_type=student
3. Create op.student.course linking student to course/batch
4. Set admission.student_id to the new student
5. Set admission.state to admission
6. Send welcome email with login credentials

---

10. Subject Registration

10.1 Model

Backed by op.subject.registration (OpenEduCat core).

10.2 API Endpoints

Method	Path	Auth	Description
GET	/api/subject-registrations	JWT	List registrations (filter: student_id, course_id, state)
POST	/api/subject-registrations	JWT	Create registration
PATCH	/api/subject-registrations/{id}	JWT	Update selected subjects
POST	/api/subject-registrations/{id}/confirm	JWT	Confirm registration
POST	/api/subject-registrations/{id}/reject	JWT	Reject registration
GET	/api/subject-registrations/available	JWT	Get available subjects for current student's enrolled courses

10.3 Available Subjects Logic

For the current user (student):

1. Find all op.student.course records for this student
2. Get subjects linked to those courses
3. Exclude subjects already registered in confirmed registrations
4. Check unit load limits from op.course configuration
5. Return list with min_unit_load, max_unit_load

---

11. Exam Engine (EnCoach AI)

11.1 Model (encoach.exam)

Field	Type	Description
name	Char	Exam title
module	Selection	reading, writing, listening, speaking, math, it, ...
subject_id	Many2one	Link to encoach.subject (taxonomy)
topic_ids	Many2many	Link to encoach.topic
entity_id	Many2one	Owning entity
structure_id	Many2one	Exam structure template
rubric_id	Many2one	Grading rubric
exercises	Text (JSON)	Generated exercises content
is_public	Boolean	Public access flag
status	Selection	draft, published, archived

11.2 API Endpoints

Method	Path	Auth	Description
GET	/api/exam/{module}	JWT	List exams for module (paginated)
GET	/api/exam/{module}/{id}	JWT	Exam detail
POST	/api/exam	JWT	Create exam
PATCH	/api/exam/{id}	JWT	Update exam
DELETE	/api/exam/{id}	JWT	Delete exam
PATCH	/api/exam/{id}/access	JWT	Set public/private
GET	/api/rubrics	JWT	List rubrics (paginated)
POST	/api/rubrics	JWT	Create rubric
GET	/api/rubric-groups	JWT	List rubric groups
GET	/api/exam-structures	JWT	List exam structures
POST	/api/exam-structures	JWT	Create exam structure
DELETE	/api/exam-structures/{id}	JWT	Delete structure
GET	/api/exam/avatars	JWT	List ELAI avatars
POST	/api/exam/{module}/generate	JWT	Generate exercises from existing exam
POST	/api/exam/{module}/generate/scratch	JWT	Generate full exam from scratch

11.3 Generation Logic

Uses OpenAI GPT-4o to generate exam content. Prompt templates vary by module:

• Reading/Listening: Passage + comprehension questions
• Writing: Task description + sample topics
• Speaking: Dialogue prompts + follow-up questions
• Math: Problem sets with numerical answers, configurable difficulty
• IT: Code completion, debugging, conceptual questions

---

12. Institutional Exams (OpenEduCat)

12.1 Overview

Traditional institutional exams (midterms, finals) managed through OpenEduCat. Separate from EnCoach AI exams.

12.2 API Endpoints

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

12.3 Enter Marks Request

{
  "attendees": [
    { "student_id": 1, "marks": 85 },
    { "student_id": 2, "marks": 72 }
  ]
}

12.4 Generate Marksheets Logic

1. Create op.marksheet.register from op.result.template
2. For each student in the batch:
   • Create op.marksheet.line
   • For each exam in the session: create op.result.line with marks from op.exam.attendees
   • Compute total marks, percentage
   • If evaluation_type is grade: lookup op.grade.configuration to assign grade
   • Compute pass/fail from min_marks on each exam
3. Compute total_pass and total_failed on register

---

13. Assignment System (EnCoach AI)

13.1 Model (encoach.assignment)

Exam-wrapper assignments where an EnCoach exam is assigned to students/classrooms.

13.2 Enhanced Fields (Late Submission + Plagiarism)

Add to encoach.assignment:

Field	Type	Description
late_deadline	Datetime	Final late submission cutoff
penalty_type	Selection	none, percentage, fixed_deduction
penalty_value	Float	Penalty amount
max_submissions	Integer	Maximum allowed submissions (0 = unlimited)
allow_extensions	Boolean	Student extension requests
plagiarism_enabled	Boolean	Enable GPTZero plagiarism check
plagiarism_max_checks	Integer	Max plagiarism checks per submission
reminder_count	Integer	Number of reminders
reminder_frequency	Selection	once, daily, custom

13.3 Extension Request Model (encoach.extension.request)

Field	Type	Description
student_id	Many2one (res.users)	Requesting student
assignment_id	Many2one	Target assignment
reason	Text	Justification
requested_date	Datetime	New deadline
status	Selection	pending, approved, rejected
approved_by	Many2one	Approving teacher
response_note	Text	Teacher response

13.4 API Endpoints

Method	Path	Auth	Description
GET	/api/assignments	JWT	Paginated assignments
GET	/api/assignments/{id}	JWT	Assignment detail
POST	/api/assignments	JWT	Create assignment (includes late submission fields)
PATCH	/api/assignments/{id}	JWT	Update assignment
DELETE	/api/assignments/{id}	JWT	Delete assignment
POST	/api/assignments/{id}/archive	JWT	Archive assignment
POST	/api/assignments/{id}/start	JWT	Start assignment (student)
POST	/api/assignments/{id}/request-extension	JWT (student)	Request deadline extension
GET	/api/assignments/{id}/extension-requests	JWT (teacher)	List extension requests
POST	/api/extension-requests/{id}/respond	JWT (teacher)	Approve/reject extension

---

14. Course Assignment Submissions (OpenEduCat)

14.1 Overview

Traditional file-based assignments where students upload work and teachers grade it. Uses OpenEduCat models.

14.2 API Endpoints

Method	Path	Auth	Description
GET	/api/course-assignments	JWT	List course assignments (filter: course_id, batch_id, state)
POST	/api/course-assignments	JWT	Create course assignment
GET	/api/course-assignments/{id}	JWT	Assignment detail with submissions
PATCH	/api/course-assignments/{id}	JWT	Update assignment
POST	/api/course-assignments/{id}/publish	JWT	Publish assignment
POST	/api/course-assignments/{id}/finish	JWT	Close assignment
GET	/api/course-assignments/{id}/submissions	JWT	List student submissions
POST	/api/course-assignments/{id}/submit	JWT	Student file upload (multipart/form-data)
PATCH	/api/submissions/{id}	JWT	Grade submission (marks, feedback, status)
GET	/api/assignment-types	JWT	List assignment types
POST	/api/assignment-types	JWT	Create assignment type

14.3 File Upload

Student submission accepts multipart/form-data:

• file: Binary file attachment
• description: Optional text description

Files are stored as ir.attachment records linked to op.assignment.sub.line.

14.4 Grading Request

{
  "marks": 85,
  "state": "accept",
  "note": "Well researched paper. Minor formatting issues."
}

---

15. Classroom and Group Management

15.1 Model (encoach.classroom.group)

Virtual classrooms for grouping students within entities.

15.2 API Endpoints

Method	Path	Auth	Description
GET	/api/groups	JWT	Paginated groups
GET	/api/groups/{id}	JWT	Group detail with members
POST	/api/groups	JWT	Create group
DELETE	/api/groups/{id}	JWT	Delete group
POST	/api/groups/transfer	JWT	Transfer students between groups
POST	/api/groups/{id}/members	JWT	Add members
POST	/api/groups/{id}/members/remove	JWT	Remove members

---

16. Subject Taxonomy Engine

16.1 Models

encoach.subject (distinct from op.subject)

Field	Type	Description
name	Char	Subject name (e.g., "IELTS", "Mathematics", "Information Technology")
code	Char	Unique code
description	Text	Description
icon	Char	Icon identifier
active	Boolean	Active flag
domain_ids	One2many	Child domains

encoach.domain

Field	Type	Description
name	Char	Domain name (e.g., "Algebra", "Networking")
subject_id	Many2one	Parent subject
topic_ids	One2many	Child topics

encoach.topic

Field	Type	Description
name	Char	Topic name
domain_id	Many2one	Parent domain
subject_id	Many2one (related)	Subject via domain
difficulty	Selection	beginner, intermediate, advanced
prerequisite_ids	Many2many	Prerequisite topics
learning_objective_ids	One2many	Learning objectives

encoach.learning.objective

Field	Type	Description
name	Char	Objective description
topic_id	Many2one	Parent topic
bloom_level	Selection	remember, understand, apply, analyze, evaluate, create

16.2 API Endpoints

Method	Path	Auth	Description
GET	/api/subjects	JWT	List subjects
GET	/api/subjects/{id}	JWT	Subject detail
POST	/api/subjects	JWT	Create subject
PATCH	/api/subjects/{id}	JWT	Update subject
DELETE	/api/subjects/{id}	JWT	Delete subject
GET	/api/subjects/{subjectId}/taxonomy	JWT	Full taxonomy tree (domains → topics → objectives)
POST	/api/subjects/{subjectId}/taxonomy/import	JWT	Import taxonomy from file (multipart)
GET	/api/domains	JWT	List domains (filter: subject_id)
POST	/api/domains	JWT	Create domain
PATCH	/api/domains/{id}	JWT	Update domain
DELETE	/api/domains/{id}	JWT	Delete domain
POST	/api/domains/{domainId}/ai-suggest	JWT	AI-suggest topics for domain
GET	/api/topics	JWT	List topics (filter: domain_id, subject_id)
POST	/api/topics	JWT	Create topic
PATCH	/api/topics/{id}	JWT	Update topic
DELETE	/api/topics/{id}	JWT	Delete topic

---

17. Adaptive Learning Engine

17.1 Models

encoach.proficiency

Field	Type	Description
student_id	Many2one	Student user
subject_id	Many2one	Subject
topic_id	Many2one	Topic
mastery_score	Float	0.0 to 1.0
confidence	Float	Statistical confidence
last_assessed	Datetime	Last assessment time
assessment_count	Integer	Number of assessments

encoach.learning.plan

Field	Type	Description
student_id	Many2one	Student
subject_id	Many2one	Subject
status	Selection	active, paused, completed
items	One2many	Plan items (topics in order)
generated_by	Selection	ai, manual
progress	Float	Computed completion percentage

encoach.learning.plan.item

Field	Type	Description
plan_id	Many2one	Parent plan
topic_id	Many2one	Topic
sequence	Integer	Order in plan
status	Selection	locked, available, in_progress, completed
estimated_hours	Float	Estimated time
mastery_threshold	Float	Required mastery to complete

encoach.diagnostic.session

Field	Type	Description
student_id	Many2one	Student
subject_id	Many2one	Subject
status	Selection	in_progress, completed
questions_answered	Integer	Count
result_data	Text (JSON)	Topic-level results

encoach.content.cache

Field	Type	Description
topic_id	Many2one	Topic
content_type	Selection	explanation, practice, quiz
content	Text (JSON)	Cached AI content
generated_at	Datetime	Generation time
ttl_hours	Integer	Cache TTL

17.2 API Endpoints

Method	Path	Auth	Description
POST	/api/diagnostic/start	JWT	Start diagnostic for subject
POST	/api/diagnostic/answer	JWT	Submit diagnostic answer (adaptive next question)
GET	/api/diagnostic/{sessionId}/result	JWT	Get diagnostic result
GET	/api/proficiency	JWT	Get proficiency records (filter: subject_id, student_id)
GET	/api/proficiency/summary	JWT	Aggregate proficiency summary
GET	/api/proficiency/class	JWT	Class-wide proficiency
GET	/api/learning-plan	JWT	Get learning plan (filter: subject_id)
POST	/api/learning-plan/generate	JWT	AI-generate learning plan
PATCH	/api/learning-plan/{id}	JWT	Update plan
POST	/api/learning-plan/{id}/pause	JWT	Pause plan
POST	/api/learning-plan/{id}/resume	JWT	Resume plan
GET	/api/topics/{topicId}/content	JWT	Get topic learning content
POST	/api/topics/{topicId}/generate-content	JWT	AI-generate topic content
POST	/api/topics/{topicId}/practice	JWT	Generate practice questions
POST	/api/topics/{topicId}/practice/grade	JWT	Grade practice answers
POST	/api/topics/{topicId}/mastery-quiz	JWT	Start mastery quiz
POST	/api/topics/{topicId}/mastery-quiz/submit	JWT	Submit mastery quiz and update proficiency

17.3 Diagnostic Algorithm

Computer Adaptive Testing (CAT):

1. Start with medium-difficulty questions
2. If correct → harder question; if incorrect → easier question
3. Uses Item Response Theory (IRT) to estimate ability
4. Covers multiple topics within the subject
5. Terminates after sufficient confidence or max questions (20-30)
6. Produces per-topic mastery scores

17.4 Learning Plan Generation

AI-generated study plan:

1. Read student's proficiency profile
2. Identify weak topics (mastery < threshold)
3. Respect prerequisite graph (topological sort)
4. Estimate time per topic based on gap
5. Order topics: prerequisites first, then weakest areas
6. Return ordered list of plan_items

---

18. Learning Resources

18.1 Model (encoach.resource)

Field	Type	Description
name	Char	Resource title
type	Selection	video, document, link, interactive
subject_id	Many2one	Subject
topic_ids	Many2many	Topics
file	Binary	Uploaded file
url	Char	External URL
difficulty	Selection	beginner, intermediate, advanced
duration_minutes	Integer	Estimated duration
active	Boolean	Soft-delete flag

18.2 API Endpoints

Method	Path	Auth	Description
GET	/api/resources	JWT	Paginated resources (filter: subject_id, topic_id, type, difficulty)
POST	/api/resources	JWT	Upload resource (multipart)
PATCH	/api/resources/{id}	JWT	Update resource metadata
DELETE	/api/resources/{id}	JWT	Soft-delete resource
POST	/api/resources/{id}/complete	JWT	Mark resource as completed by student
POST	/api/resources/{id}/rate	JWT	Rate resource (1-5)
GET	/api/resources/{id}/download	JWT	Download resource file

---

19. AI Services

19.1 AI Coaching

Method	Path	Auth	Description
POST	/api/coach/chat	JWT	General AI chat (context-aware)
POST	/api/coach/hint	JWT	Hint for topic/question
POST	/api/coach/explain	JWT	Explain scores or concepts
POST	/api/coach/suggest	JWT	Study suggestions
POST	/api/coach/writing-help	JWT	Writing feedback with improved text
GET	/api/coach/tip	JWT	Context-aware tip (FAISS similarity)

19.2 AI Evaluation

Method	Path	Auth	Description
POST	/api/evaluate/writing	JWT	Evaluate writing (IELTS band scoring / rubric-based)
POST	/api/evaluate/speaking	JWT	Evaluate speaking (audio → transcribe → grade)
POST	/api/grading/multiple	JWT	Grade multiple-choice / numerical answers
POST	/api/transcribe	JWT	Audio transcription (Whisper, multipart upload)

19.3 AI Generation

Method	Path	Auth	Description
POST	/api/exam/{module}/generate	JWT	Generate exam exercises from template
POST	/api/exam/{module}/generate/scratch	JWT	Generate full exam from scratch

19.4 Media Generation

Method	Path	Auth	Description
POST	/api/exam/listening/media	JWT	Generate listening audio (AWS Polly TTS)
POST	/api/exam/speaking/media	JWT	Generate speaking video (ELAI)
GET	/api/exam/avatars	JWT	List ELAI avatars with voice metadata

19.5 AI Analytics

Method	Path	Auth	Description
POST	/api/ai/search	JWT	AI-powered semantic search
POST	/api/ai/insights	JWT	AI-generated insights from data
GET	/api/ai/alerts	JWT	AI-detected alerts (at-risk students, anomalies)
POST	/api/ai/report-narrative	JWT	AI narrative for reports
POST	/api/ai/batch-optimize	JWT	Batch optimization suggestions
POST	/api/ai/grade-suggest	JWT	AI grading suggestion

19.6 AI Service Configuration

All AI services read configuration from ir.config_parameter:

Parameter Key	Description	Default
encoach.openai_api_key	OpenAI API key	Required
encoach.openai_model	Default model	gpt-4o
encoach.openai_model_light	Light model for simple tasks	gpt-3.5-turbo
encoach.aws_access_key_id	AWS access key	Required
encoach.aws_secret_access_key	AWS secret key	Required
encoach.aws_region	AWS region	eu-west-1
encoach.polly_voice_id	Default Polly voice	Joanna
encoach.polly_engine	Polly engine	neural
encoach.whisper_model	Whisper model size	base
encoach.whisper_workers	Whisper worker threads	4
encoach.elai_api_key	ELAI API key	Required
encoach.gptzero_api_key	GPTZero API key	Required
encoach.faiss_embedding_model	Sentence transformer model	all-MiniLM-L6-v2

---

20. Training Content

20.1 Models

encoach.training.tip

Field	Type	Description
title	Char	Tip title
content	Text	Tip content
subject_id	Many2one	Subject
module	Char	Module tag
embedding	Binary(attachment=False)	FAISS embedding vector

encoach.training.walkthrough

Field	Type	Description
title	Char	Walkthrough title
steps	Text (JSON)	Step-by-step content
module	Char	Module tag

20.2 API Endpoints

Method	Path	Auth	Description
GET	/api/training	JWT	Training records (filter: entity_id, user_id, module)
GET	/api/training/tips	JWT	Training tips
GET	/api/training/walkthrough	JWT	Walkthroughs (filter: module)

---

21. Analytics and Statistics

21.1 API Endpoints

Method	Path	Auth	Description
GET	/api/sessions	JWT	Exam sessions
GET	/api/stats	JWT	Exam statistics
GET	/api/statistical	JWT	Aggregated statistical data
GET	/api/stats/performance	JWT	Performance metrics
GET	/api/analytics/student	JWT	Student analytics (filter: student_id, subject_id, date_range)
GET	/api/analytics/class	JWT	Class analytics (filter: batch_id, course_id)
GET	/api/analytics/subject	JWT	Subject analytics (filter: subject_id)
GET	/api/analytics/content-gaps	JWT	Content gap analysis

---

22. Subscription and Payments

22.1 Models

encoach.package

Field	Type	Description
name	Char	Package name
description	Text	Description
price	Float	Price
currency	Char	Currency code
duration_days	Integer	Access duration
subject_ids	Many2many	Included subjects
features	Text (JSON)	Feature list
active	Boolean	Available for purchase

encoach.payment

Field	Type	Description
user_id	Many2one	Paying user
entity_id	Many2one	Entity (if institutional)
package_id	Many2one	Package
amount	Float	Payment amount
currency	Char	Currency
provider	Selection	stripe, paypal, paymob, invoice
status	Selection	pending, completed, failed, refunded
provider_ref	Char	External reference
created_at	Datetime	Payment date

encoach.discount

Field	Type	Description
code	Char	Discount code
percentage	Float	Discount percentage
valid_from	Datetime	Start date
valid_to	Datetime	End date
max_uses	Integer	Maximum uses
current_uses	Integer	Current use count

22.2 API Endpoints

Method	Path	Auth	Description
GET	/api/packages	JWT	List packages
GET	/api/payments	JWT	Paginated payments
POST	/api/stripe/checkout	JWT	Create Stripe checkout session, return URL
POST	/api/paypal/checkout	JWT	Create PayPal order, return approval URL
POST	/api/paymob/checkout	JWT	Create Paymob payment, return URL
GET	/api/discounts	JWT	List discounts
POST	/api/discounts	JWT	Create discount
DELETE	/api/discounts/{id}	JWT	Delete discount

22.3 Webhook Endpoints

Method	Path	Auth	Description
POST	/api/stripe/webhook	Webhook signature	Stripe payment events
POST	/api/paypal/webhook	Webhook signature	PayPal payment events
POST	/api/paymob/webhook	Webhook HMAC	Paymob transaction callback

---

23. Support Tickets

23.1 Model (encoach.ticket)

Field	Type	Description
subject	Char	Ticket subject
description	Text	Description
type	Selection	bug, feature, support, feedback
status	Selection	open, in_progress, resolved, closed
reporter_id	Many2one	Reporter user
assignee_id	Many2one	Assigned staff
entity_id	Many2one	Entity context
source	Selection	platform, webpage

23.2 API Endpoints

Method	Path	Auth	Description
GET	/api/tickets	JWT	Paginated tickets (filter: status, type, assignee_id, source)
POST	/api/tickets	JWT	Create ticket
PATCH	/api/tickets/{id}	JWT	Update ticket
GET	/api/tickets/assignedToUser	JWT	Tickets assigned to current user

---

24. File Storage

24.1 API Endpoints

Method	Path	Auth	Description
POST	/api/storage/upload	JWT	Upload file (multipart/form-data), return attachment ID and URL
GET	/api/storage/url	JWT	Resolve download URL for filename

Files are stored as ir.attachment records. For production, configure Odoo to use S3-compatible storage.

---

25. Approval Workflows (Enhanced)

25.1 Model (encoach.approval.workflow)

Field	Type	Description
name	Char	Workflow name
type	Selection	exam_publish, assignment_publish, content_publish, material_publish
stage_ids	One2many	Approval stages (ordered)
entity_id	Many2one	Entity
allow_bypass	Boolean	Whether bypass is allowed
active	Boolean	Active flag

25.2 Model (encoach.approval.stage)

Field	Type	Description
workflow_id	Many2one	Parent workflow
sequence	Integer	Stage order
approver_id	Many2one	Assigned approver (res.users)
max_days	Integer	Maximum days before auto-escalation
auto_escalate	Boolean	Whether to auto-escalate on timeout
notification_email	Char	Email for stage notifications
status	Selection	pending, approved, rejected, escalated, bypassed
comment	Text	Reviewer comment
acted_at	Datetime	When action was taken

25.3 Model (encoach.approval.request)

Field	Type	Description
workflow_id	Many2one	Workflow template
res_model	Char	Target model (e.g., encoach.exam)
res_id	Integer	Target record ID
current_stage_id	Many2one	Current active stage
requester_id	Many2one	User who submitted for approval
state	Selection	in_progress, approved, rejected, bypassed
bypass_reason	Text	Justification if bypassed
created_at	Datetime	Request creation time

25.4 API Endpoints

Method	Path	Auth	Description
GET	/api/approval-workflows	JWT	Paginated workflows
POST	/api/approval-workflows	JWT	Create workflow with stages
GET	/api/approval-workflows/{id}	JWT	Get workflow with stages
PATCH	/api/approval-workflows/{id}	JWT	Update workflow and stages
DELETE	/api/approval-workflows/{id}	JWT	Delete workflow
POST	/api/approval-requests	JWT	Submit item for approval
GET	/api/approval-requests	JWT	List approval requests (filter: state, type)
POST	/api/approval-requests/{id}/approve	JWT	Approve current stage
POST	/api/approval-requests/{id}/reject	JWT	Reject at current stage
POST	/api/approval-requests/{id}/bypass	JWT	Bypass approval (requires justification)
POST	/api/approval-requests/{id}/return	JWT	Return to specific stage

25.5 Cron: Auto-Escalation

A server cron runs daily to check approval stages that have exceeded max_days. For stages with auto_escalate = True, the system automatically advances to the next stage and sends a notification email to the new approver with escalation reason.

---

26. Courseware and Content Delivery

Module: encoach_courseware
Dependencies: encoach_core, openeducat_core, encoach_ai

26.1 Model (encoach.course.chapter)

Field	Type	Description
name	Char (required)	Chapter title
course_id	Many2one (op.course)	Parent 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, manual, prerequisite
is_unlocked	Boolean	Current unlock status
topic_id	Many2one (encoach.topic)	Bridge to adaptive engine
material_ids	One2many	Chapter materials
assignment_ids	Many2many (encoach.assignment)	Linked assignments
exam_ids	Many2many (encoach.exam)	Linked exams/quizzes
active	Boolean	Soft-delete flag

26.2 Model (encoach.chapter.material)

Field	Type	Description
name	Char (required)	Material title
chapter_id	Many2one	Parent chapter
type	Selection	pdf, document, video, audio, image, link, article
file	Binary (attachment=True)	Uploaded file
url	Char	External URL
description	Text	Description
sequence	Integer	Display order
allow_download	Boolean	Student download permission
is_book	Boolean	Course book flag
book_chapters	Text	JSON book chapter structure
active	Boolean	Soft-delete flag

26.3 Model (encoach.chapter.progress)

Field	Type	Description
student_id	Many2one (res.users)	Student
chapter_id	Many2one	Chapter
status	Selection	not_started, in_progress, completed
started_at	Datetime	First access time
completed_at	Datetime	Completion time
materials_completed	Integer	Count of materials viewed
materials_total	Integer	Computed total materials

26.4 API Endpoints

Method	Path	Auth	Description
GET	/api/courses/{courseId}/chapters	JWT	List chapters (ordered by sequence)
POST	/api/courses/{courseId}/chapters	JWT (teacher)	Create chapter
GET	/api/chapters/{id}	JWT	Chapter detail with material count
PATCH	/api/chapters/{id}	JWT (teacher)	Update chapter
DELETE	/api/chapters/{id}	JWT (teacher)	Soft-delete chapter
POST	/api/chapters/{id}/unlock	JWT (teacher)	Manually unlock
POST	/api/chapters/{id}/lock	JWT (teacher)	Manually lock
PATCH	/api/courses/{courseId}/chapters/reorder	JWT (teacher)	Reorder (body: {ids: []})
GET	/api/chapters/{id}/progress	JWT	Student progress
POST	/api/chapters/{id}/progress/complete	JWT (student)	Mark chapter completed
GET	/api/chapters/{chapterId}/materials	JWT	List materials
POST	/api/chapters/{chapterId}/materials	JWT (teacher)	Upload material (multipart)
PATCH	/api/materials/{id}	JWT (teacher)	Update material metadata
DELETE	/api/materials/{id}	JWT (teacher)	Delete material
GET	/api/materials/{id}/download	JWT	Download file (streaming response)
POST	/api/materials/{id}/viewed	JWT (student)	Record material view
PATCH	/api/chapters/{chapterId}/materials/reorder	JWT (teacher)	Reorder materials

26.5 AI Workbench Endpoints

Method	Path	Auth	Description
POST	/api/workbench/generate-outline	JWT (teacher)	AI generates course outline from requirements (topic, objectives, complexity)
POST	/api/workbench/generate-chapter	JWT (teacher)	AI generates content for a specific chapter
POST	/api/workbench/generate-rubric	JWT (teacher)	AI generates grading rubric
POST	/api/workbench/regenerate	JWT (teacher)	Regenerate specific section
POST	/api/workbench/suggest-materials	JWT (teacher)	AI suggests supplementary materials based on student performance profiles
POST	/api/workbench/publish	JWT (teacher)	Publish generated content to course chapters (may trigger approval workflow)

AI Workbench uses GPT-4o (temp 0.7 for generation) and calls encoach_ai service layer.

26.6 Cron: Auto-Unlock Chapters

Server cron runs every hour. For chapters with unlock_mode = 'auto_date' and start_date <= now() and is_unlocked = False, set is_unlocked = True and trigger notification.

---

27. Communication System

Module: encoach_communication
Dependencies: encoach_core, openeducat_core

27.1 Model (encoach.discussion.board)

Field	Type	Description
name	Char (required)	Board title
course_id	Many2one (op.course)	Associated course
batch_id	Many2one (op.batch)	Associated batch (optional)
chapter_id	Many2one (encoach.course.chapter)	Associated chapter (optional)
assignment_id	Many2one	Associated assignment (optional)
is_enabled	Boolean	Teacher toggle
allow_student_posts	Boolean	Student thread creation permission
post_count	Integer	Computed count of posts

27.2 Model (encoach.discussion.post)

Field	Type	Description
board_id	Many2one	Parent board
parent_id	Many2one (self)	Parent post for threading
author_id	Many2one (res.users)	Author
title	Char	Thread title (root posts only)
content	Text	Post body (markdown)
attachment_ids	Many2many (ir.attachment)	File attachments
is_pinned	Boolean	Teacher pin
is_resolved	Boolean	Resolved flag (Q&A mode)
reply_count	Integer	Computed child count
created_at	Datetime	Post timestamp

27.3 Model (encoach.announcement)

Field	Type	Description
title	Char (required)	Announcement title
content	Text	Body (markdown)
author_id	Many2one (res.users)	Author
course_id	Many2one (op.course)	Target course (null = system-wide)
batch_id	Many2one (op.batch)	Target batch (null = all batches)
priority	Selection	normal, important, urgent
is_published	Boolean	Published status
published_at	Datetime	Publish timestamp
expires_at	Datetime	Expiry time
send_email	Boolean	Also send via email
attachment_ids	Many2many (ir.attachment)	Attachments

27.4 Model (encoach.message)

Field	Type	Description
sender_id	Many2one (res.users)	Sender
recipient_id	Many2one (res.users)	Recipient
subject	Char	Subject line
content	Text	Message body
is_read	Boolean	Read flag
read_at	Datetime	Read timestamp
attachment_ids	Many2many (ir.attachment)	Attachments
send_email_copy	Boolean	Send email copy
created_at	Datetime	Sent time

27.5 API Endpoints

Method	Path	Auth	Description
GET	/api/discussion-boards	JWT	List boards (filter: course_id, batch_id)
POST	/api/discussion-boards	JWT (teacher)	Create board
PATCH	/api/discussion-boards/{id}	JWT (teacher)	Update settings
GET	/api/discussion-boards/{id}/posts	JWT	Paginated posts (threaded)
POST	/api/discussion-boards/{id}/posts	JWT	Create post/reply
PATCH	/api/posts/{id}	JWT	Update own post
DELETE	/api/posts/{id}	JWT (teacher/admin)	Delete post
POST	/api/posts/{id}/pin	JWT (teacher)	Pin/unpin toggle
POST	/api/posts/{id}/resolve	JWT (teacher)	Mark as resolved
GET	/api/announcements	JWT	List announcements (filter: course_id, priority)
POST	/api/announcements	JWT (teacher/admin)	Create announcement
PATCH	/api/announcements/{id}	JWT	Update
DELETE	/api/announcements/{id}	JWT	Delete
POST	/api/announcements/{id}/publish	JWT	Publish
GET	/api/messages	JWT	Inbox (filter: is_read)
GET	/api/messages/sent	JWT	Sent messages
POST	/api/messages	JWT	Send message
GET	/api/messages/{id}	JWT	Message detail (auto-marks read)
DELETE	/api/messages/{id}	JWT	Delete message
GET	/api/messages/unread-count	JWT	Unread count {count: N}

27.6 Email Integration

When send_email = True on announcements or send_email_copy = True on messages, the module uses Odoo's mail.thread mixin to send emails through the configured outgoing mail server.

---

28. Notification Engine

Module: encoach_notification
Dependencies: encoach_core

28.1 Model (encoach.notification)

Field	Type	Description
user_id	Many2one (res.users)	Recipient
title	Char	Notification title
message	Text	Body
type	Selection	deadline, chapter_unlock, result_release, announcement, assignment, exam, message, system
action_url	Char	Frontend URL to navigate to
is_read	Boolean	Read status
read_at	Datetime	Read timestamp
channel	Selection	in_app, email, both
created_at	Datetime	Created time

28.2 Model (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 trigger
frequency	Selection	once, daily, custom
custom_intervals	Text (JSON)	Custom intervals array (e.g., [7, 3, 1])
channel	Selection	in_app, email, both
entity_id	Many2one	Entity scope
active	Boolean	Active flag

28.3 Model (encoach.notification.preferences)

Field	Type	Description
user_id	Many2one (res.users)	One per user
email_enabled	Boolean	Master email toggle
assignment_alerts	Boolean	Assignment notifications
exam_alerts	Boolean	Exam notifications
chapter_alerts	Boolean	Chapter unlock notifications
announcement_alerts	Boolean	Announcement notifications
message_alerts	Boolean	Message notifications

28.4 API Endpoints

Method	Path	Auth	Description
GET	/api/notifications	JWT	Paginated list (filter: type, is_read)
POST	/api/notifications/{id}/read	JWT	Mark as read
POST	/api/notifications/read-all	JWT	Mark all as read
GET	/api/notifications/unread-count	JWT	{count: N}
GET	/api/notification-rules	JWT (admin)	List rules
POST	/api/notification-rules	JWT (admin)	Create rule
PATCH	/api/notification-rules/{id}	JWT (admin)	Update rule
DELETE	/api/notification-rules/{id}	JWT (admin)	Delete rule
GET	/api/notification-preferences	JWT	Get user preferences
PATCH	/api/notification-preferences	JWT	Update preferences

28.5 Crons

1. Deadline Reminders: Runs daily. Checks all active rules, matches upcoming events (assignments, exams) within days_before, creates notifications and sends emails per user preferences.
2. Chapter Unlock Notifications: Triggered by the courseware cron when chapters are auto-unlocked.

---

29. FAQ System

Module: encoach_faq
Dependencies: encoach_core

29.1 Model (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

29.2 Model (encoach.faq.item)

Field	Type	Description
question	Char	Question text
answer	Text	Answer (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

29.3 API Endpoints

Method	Path	Auth	Description
GET	/api/faq/categories	Public/JWT	List categories (filter: audience)
POST	/api/faq/categories	JWT (admin)	Create category
PATCH	/api/faq/categories/{id}	JWT (admin)	Update category
DELETE	/api/faq/categories/{id}	JWT (admin)	Delete category
GET	/api/faq/items	Public/JWT	List items (filter: category_id, audience, search)
POST	/api/faq/items	JWT (admin)	Create item
PATCH	/api/faq/items/{id}	JWT (admin)	Update item
DELETE	/api/faq/items/{id}	JWT (admin)	Delete item

---

30. Plagiarism Detection

Module enhancement: encoach_ai_grading (add plagiarism sub-service)

30.1 Plagiarism Report Storage

Add to encoach.submission or create encoach.plagiarism.report:

Field	Type	Description
submission_id	Many2one	Target submission
overall_score	Float	AI probability score (0-1)
per_sentence	Text (JSON)	Per-sentence analysis from GPTZero
report_pdf	Binary	Generated PDF report
checked_at	Datetime	When check was run

30.2 API Endpoints

Method	Path	Auth	Description
POST	/api/plagiarism/check	JWT (teacher)	Submit text for GPTZero analysis
GET	/api/plagiarism/report/{submissionId}	JWT	Get plagiarism report
GET	/api/plagiarism/report/{submissionId}/download	JWT	Download PDF report

30.3 Integration

• Uses GPTZero v2/predict/text endpoint (already configured in encoach_ai_grading)
• Can be enabled/disabled per assignment via plagiarism_enabled boolean on encoach.assignment
• Configurable max submissions for plagiarism check via plagiarism_max_checks integer

---

31. Official Exam Access

Module enhancement: encoach_exam (add official access modes)

31.1 Model Extensions

Add to encoach.exam:

Field	Type	Description
is_exercise	Boolean	Exercise (practice, no journey tracking) vs Exam
is_official	Boolean	Official exam flag
access_mode	Selection	normal, link, landing_page, separate_login
access_token	Char	Unique access token (auto-generated)
access_code	Char	Exam access code
activation_start	Datetime	Exam start time
activation_end	Datetime	Exam end time
generate_unique_per_student	Boolean	AI generates unique variant per student
reminder_count	Integer	Number of reminders to send
reminder_frequency	Selection	once, daily, custom

31.2 API Endpoints

Method	Path	Auth	Description
POST	/api/exam/{id}/generate-link	JWT (teacher)	Generate unique access token/URL
GET	/api/exam/access/{token}	Public	Access exam via token (validates token, returns exam info)
POST	/api/exam/official-login	Public	Login with exam code + credentials
POST	/api/exam/{id}/suspend	JWT (teacher)	Suspend exam
POST	/api/exam/{id}/revoke	JWT (teacher)	Revoke exam access

---

32. Non-Functional Requirements

32.1 Performance

ID	Requirement
NFR-PERF-01	API response time < 500ms for CRUD endpoints
NFR-PERF-02	AI endpoints may take up to 30s (use async job for long operations)
NFR-PERF-03	Pagination: default size=20, max size=100

32.2 Security

ID	Requirement
NFR-SEC-01	JWT tokens expire after 24 hours
NFR-SEC-02	All endpoints validate entity-scoped permissions
NFR-SEC-03	Rate limiting on AI endpoints (configurable)
NFR-SEC-04	CORS configured for frontend origin
NFR-SEC-05	File upload size limit: 50MB
NFR-SEC-06	API keys stored in ir.config_parameter, never in code

32.3 Scalability

ID	Requirement
NFR-SCALE-01	Support 10,000+ concurrent students
NFR-SCALE-02	Support 50+ subjects, 500+ topics per subject, 1000+ resources per subject
NFR-SCALE-03	Database indices on all foreign keys and frequently filtered fields

32.4 Reliability

ID	Requirement
NFR-REL-01	AI service failures return graceful error (never 500)
NFR-REL-02	Webhook processing is idempotent
NFR-REL-03	Soft-delete for resources (preserve completion records)

32.5 API Conventions

Convention	Detail
Date format	ISO 8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)
Pagination	?page=1&size=20 returns { "items": [...], "total": N, "page": 1, "size": 20 }
Error shape	{ "error": "message", "code": "ERROR_CODE" } with HTTP status
ID fields	Many2one serialized as {field}_id (int) + {field}_name (str)
List fields	Many2many serialized as {field}_ids (int[]) + {field}_names (str[])
Binary fields	Base64-encoded strings or separate download endpoint
Auth header	Authorization: Bearer <jwt_token>

---

33. Implementation Status

All modules have been implemented and deployed. The original priority ordering is preserved for reference.

Priority	Modules	Status
P0	encoach_core, encoach_api (auth, users, entities, permissions)	DONE
P0	openeducat_core (port to v19), encoach_lms_api	DONE
P1	encoach_taxonomy, encoach_adaptive, encoach_adaptive_api, encoach_adaptive_ai	DONE
P1	encoach_exam, encoach_ai_generation, encoach_ai_grading	DONE
P1	encoach_resources	DONE
P2	encoach_courseware (chapters, materials, progress, AI workbench)	DONE
P2	encoach_communication (discussions, announcements, messaging)	DONE
P2	openeducat_timetable, openeducat_attendance, openeducat_classroom	DONE
P2	openeducat_admission + admission endpoints	DONE
P2	Academic years/terms, departments endpoints	DONE
P2	encoach_ai, encoach_ai_media	DONE
P2	encoach_assignment, encoach_classroom	DONE
P3	encoach_notification (rules, email delivery, preferences)	DONE
P3	Enhanced approval workflows (stages, escalation, bypass)	DONE
P3	Plagiarism detection (GPTZero integration)	DONE
P3	Official exam access modes (link, landing, separate login)	DONE
P3	Late submission handling, extension requests	DONE
P3	openeducat_exam + institutional exam endpoints	DONE
P3	openeducat_assignment + submission endpoints	DONE
P3	Subject registration endpoints	DONE
P3	encoach_training, analytics endpoints	DONE
P3	encoach_sis, encoach_branding	DONE
P4	encoach_faq (categories, items, role-filtered)	DONE
P4	encoach_subscription (Stripe, PayPal, Paymob)	DONE
P4	encoach_ticket	DONE
P4	Storage	DONE

---

34. Beyond-SRS Features (Implemented)

The developer implemented the following features beyond the original SRS scope. These leverage OpenEduCat Enterprise modules and add significant institutional management capabilities.

34.1 Student Leave Management

Module: openeducat_student_leave_enterprise (via encoach_lms_api) Controller: encoach_lms_api/controllers/student_leave.py Frontend: student-leave.service.ts | AdminStudentLeave.tsx

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

34.2 Fees Management

Module: openeducat_fees (via encoach_lms_api) Controller: encoach_lms_api/controllers/fees.py Frontend: fees.service.ts | AdminFees.tsx

Method	Path	Description
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

34.3 Lessons Management

Module: openeducat_lesson (via encoach_lms_api) Controller: encoach_lms_api/controllers/lessons.py Frontend: lesson.service.ts | AdminLessons.tsx

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

34.4 Gradebook and Grading Assignments

Module: openeducat_grading (via encoach_lms_api) Controller: encoach_lms_api/controllers/gradebook.py Frontend: gradebook.service.ts | AdminGradebook.tsx

Method	Path	Description
GET	/api/gradebooks	List gradebooks
GET	/api/gradebook-lines	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

34.5 Student Progress Tracking

Module: openeducat_student_progress_enterprise (via encoach_lms_api) Controller: encoach_lms_api/controllers/student_progress.py Frontend: student-progress.service.ts | AdminStudentProgress.tsx

Method	Path	Description
GET	/api/student-progress	List student progression records

34.6 Library Management

Module: openeducat_library (via encoach_lms_api) Controller: encoach_lms_api/controllers/library.py Frontend: library.service.ts | AdminLibrary.tsx

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

34.7 Activity Management

Module: openeducat_activity (via encoach_lms_api) Controller: encoach_lms_api/controllers/activities.py Frontend: activity.service.ts | AdminActivities.tsx

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

34.8 Facility and Asset Management

Module: openeducat_facility (extended via encoach_lms_api) Controller: encoach_lms_api/controllers/facilities.py Frontend: facility.service.ts | AdminFacilities.tsx

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

34.9 Roles CRUD, User Role Assignment, and Authority Matrix

Module: encoach_core (extended) Controller: encoach_api/controllers/roles.py Frontend: entities.service.ts | RolesPermissions.tsx, UserRoles.tsx, AuthorityMatrix.tsx

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
GET	/api/users/with-roles	List users with roles
GET/PATCH	/api/users/{id}/roles	Get/update user roles
POST	/api/users/{id}/roles/toggle	Toggle role for user
GET	/api/authority-matrix	Get role-permission matrix
POST	/api/authority-matrix/toggle	Toggle a matrix cell
GET	/api/user-authority-matrix	Get user-level authority

---

Appendix A: Complete Endpoint Summary (Verified Against Deployment)

Total API endpoints: ~377 (deployed across 4 controller packages)

Controller Package	Route Count	Service Areas
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)

Breakdown by Service Area:

Service Area	Endpoint Count	Status
Auth & Users	10	Deployed
Entities & Permissions	9	Deployed
Roles CRUD & Authority Matrix	12	Deployed (Beyond SRS)
LMS (Courses, Batches, Timetable, Attendance, Grades)	16	Deployed
Academic Years, Terms, Departments	14	Deployed
Admissions	12	Deployed
Subject Registration	6	Deployed
EnCoach Exams (AI)	15	Deployed
Institutional Exams	21	Deployed
EnCoach Assignments	7	Deployed
Course Assignments & Submissions	11	Deployed
Classrooms & Groups	7	Deployed
Taxonomy	16	Deployed
Adaptive Learning	17	Deployed
Resources	7	Deployed
AI Coaching	6	Deployed
AI Evaluation	4	Deployed
AI Generation	2	Deployed
AI Media	3	Deployed
AI Analytics	6	Deployed
Training	3	Deployed
Statistics	4	Deployed
Subscriptions & Payments	8 + 3 webhooks	Deployed
Tickets	4	Deployed
Storage	2	Deployed
Approval Workflows (Enhanced)	11	Deployed
Courseware (Chapters + Materials + Workbench)	23	Deployed
Discussion Boards + Posts	9	Deployed
Announcements	5	Deployed
Messaging	6	Deployed
Notifications + Rules + Preferences	10	Deployed
FAQ (Categories + Items)	8	Deployed
Plagiarism Detection	3	Deployed
Official Exam Access	5	Deployed
Student Leave Management	7	Deployed (Beyond SRS)
Fees Management	4	Deployed (Beyond SRS)
Lessons Management	4	Deployed (Beyond SRS)
Gradebook & Grading	6	Deployed (Beyond SRS)
Student Progress	1	Deployed (Beyond SRS)
Library Management	9	Deployed (Beyond SRS)
Activity Management	7	Deployed (Beyond SRS)
Facility & Asset Management	7	Deployed (Beyond SRS)

---

Appendix B: Model Relationship Diagram

res.users ──extends──> encoach.user
    │                      │
    │                      ├── entity_ids ──> encoach.entity
    │                      │                     └── role_ids ──> encoach.role
    │                      │                                        └── permission_ids ──> encoach.permission
    │                      │
    │                      ├── op_student_id ──> op.student ──> op.student.course ──> op.course
    │                      │                                                            ├── op.batch
    │                      │                                                            ├── op.subject
    │                      │                                                            └── op.department
    │                      │
    │                      └── op_faculty_id ──> op.faculty
    │
    ├── encoach.exam ──> encoach.subject (taxonomy)
    │                        ├── encoach.domain
    │                        │       └── encoach.topic
    │                        │               ├── encoach.learning.objective
    │                        │               ├── encoach.proficiency
    │                        │               └── encoach.resource
    │                        │
    │                        └── encoach.learning.plan
    │                                └── encoach.learning.plan.item ──> encoach.topic
    │
    ├── op.academic.year ──> op.academic.term
    │
    ├── op.admission.register ──> op.admission ──> op.student
    │
    ├── op.exam.session ──> op.exam ──> op.exam.attendees
    │                                       └── op.marksheet.register ──> op.marksheet.line
    │
    ├── op.assignment ──> op.assignment.sub.line (submissions)
    │
    ├── encoach.course.chapter ──> op.course
    │       ├── encoach.chapter.material
    │       ├── encoach.chapter.progress ──> res.users
    │       └── encoach.topic (bridge to adaptive)
    │
    ├── encoach.discussion.board ──> op.course / op.batch / encoach.course.chapter
    │       └── encoach.discussion.post (self-referencing for threads)
    │
    ├── encoach.announcement ──> op.course / op.batch
    │
    ├── encoach.message ──> res.users (sender/recipient)
    │
    ├── encoach.notification ──> res.users
    │       └── encoach.notification.rule (event triggers)
    │
    ├── encoach.faq.category ──> encoach.faq.item
    │
    ├── encoach.approval.workflow ──> encoach.approval.stage
    │       └── encoach.approval.request
    │
    └── encoach.plagiarism.report ──> submission

---

This SRS is the definitive backend specification for the EnCoach platform on Odoo 19. All ~377 REST API endpoints, 41 Odoo modules (14 OpenEduCat + 27 custom), and all AI service integrations have been implemented and deployed to staging at http://5.189.151.117:8069. All previous backend SRS documents (ODOO_BACKEND_SRS_v3.md, ODOO_MIGRATION_SRS_v2.md, ODOO_MIGRATION_SRS.md) are superseded by this document.