encoach_frontend_new_v1/docs/ENCOACH_ODOO19_BACKEND_SRS.md

EnCoach Platform — Odoo 19 Backend SRS

Version: 1.0
Date: March 2026
Status: Definitive
Purpose: Complete backend specification for an Odoo 19 developer to build all required modules, models, and REST API endpoints for the EnCoach Adaptive Learning Platform.

---

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
26. Non-Functional Requirements
27. Implementation Priority

---

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

Total: 8 OpenEduCat (ported) + 23 custom = 31 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 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
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)

---

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

25.1 Model (encoach.approval.workflow)

Field	Type	Description
name	Char	Workflow name
type	Selection	exam_publish, assignment_publish, content_publish
steps	One2many	Approval steps
entity_id	Many2one	Entity
active	Boolean	Active flag

25.2 API Endpoints

Method	Path	Auth	Description
GET	/api/approval-workflows	JWT	Paginated workflows
POST	/api/approval-workflows	JWT	Create workflow
PATCH	/api/approval-workflows/{id}	JWT	Update workflow
DELETE	/api/approval-workflows/{id}	JWT	Delete workflow

---

26. Non-Functional Requirements

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

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

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

26.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)

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

---

27. Implementation Priority

Priority	Modules	Rationale
P0	encoach_core, encoach_api (auth, users, entities, permissions)	Foundation — blocks everything
P0	openeducat_core (port to v19), encoach_lms_api (courses, batches, basic serialization)	LMS foundation
P1	encoach_taxonomy, encoach_adaptive, encoach_adaptive_api, encoach_adaptive_ai	Core adaptive learning loop
P1	encoach_exam, encoach_ai_generation, encoach_ai_grading	Exam engine
P1	encoach_resources	Learning content
P2	openeducat_timetable, openeducat_attendance, openeducat_classroom (port to v19)	LMS timetable/attendance
P2	openeducat_admission (port to v19) + admission endpoints	Enrollment workflow
P2	Academic years/terms, departments endpoints	Institutional calendar
P2	encoach_ai, encoach_ai_media	AI services + media
P2	encoach_assignment, encoach_classroom	Assignments + groups
P3	openeducat_exam (port to v19) + institutional exam endpoints	Institutional assessment
P3	openeducat_assignment (port to v19) + submission endpoints	Homework workflow
P3	Subject registration endpoints	Student subject selection
P3	encoach_training, analytics endpoints	Training + analytics
P3	encoach_sis, encoach_branding	University integration
P4	encoach_subscription (Stripe, PayPal, Paymob)	Payments
P4	encoach_ticket	Support
P4	Approval workflows, storage	Operational features

---

Appendix A: Complete Endpoint Summary

Total API endpoints: 200+

Service Area	Endpoint Count
Auth & Users	10
Entities & Permissions	9
LMS (Courses, Batches, Timetable, Attendance, Grades)	16
Academic Years, Terms, Departments	14
Admissions	12
Subject Registration	6
EnCoach Exams (AI)	15
Institutional Exams	21
EnCoach Assignments	7
Course Assignments & Submissions	11
Classrooms & Groups	7
Taxonomy	16
Adaptive Learning	17
Resources	7
AI Coaching	6
AI Evaluation	4
AI Generation	2
AI Media	3
AI Analytics	6
Training	3
Statistics	4
Subscriptions & Payments	8 + 3 webhooks
Tickets	4
Storage	2
Approval Workflows	4

---

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)

---

This SRS is the definitive backend specification for the EnCoach platform on Odoo 19. It covers all 200+ REST API endpoints expected by the React frontend, all Odoo models (OpenEduCat + custom), and all AI service integrations.