encoach_backend_new_v2/new_project/ODOO_BACKEND_SRS_v3.md

EnCoach Odoo 19 Backend -- Developer SRS v3

Document Version: 3.0 Date: March 11, 2026 Status: Active -- Ready for Development Supersedes: ODOO_MIGRATION_SRS_v2.md (v2.0) Master Reference: ENCOACH_UNIFIED_SRS.md (v1.0) Author: EnCoach Architecture Team

---

Purpose

This document is the backend implementation specification for the Odoo 19 developer. It defines every API endpoint, data model, and module the frontend expects. The frontend is fully built and wired -- it makes real HTTP calls to these endpoints via TanStack Query. Your job is to ensure every endpoint listed here exists, returns the correct response shape, and connects to the correct Odoo models.

Source of truth for response shapes: encoach_frontend_new/src/types/*.ts (14 files) Source of truth for endpoint paths: encoach_frontend_new/src/services/*.ts (21 files)

---

Table of Contents

1. What Already Exists
2. What Needs to Be Built or Modified
3. New Odoo Modules
4. Existing Module Modifications
5. Complete API Contract
6. Data Model Specification
7. AI Service Integration
8. Response Format Standards
9. Non-Functional Requirements
10. Implementation Priority

---

1. What Already Exists

1.1 Existing Odoo Modules (15)

These modules are built and deployed in ielts-be-v0/:

#	Module	Controller File	Endpoints
1	encoach_core	--	Users, entities, roles, permissions, codes, invites
2	encoach_ai	--	OpenAI service wrapper, constants, blacklist
3	encoach_ai_media	media.py	TTS (Polly), STT (Whisper), ELAI avatars
4	encoach_ai_generation	generation.py	Exam content generation per module
5	encoach_ai_grading	grading.py	Writing/speaking AI grading
6	encoach_exam	exams.py	Exam CRUD, approval workflows
7	encoach_assignment	assignments.py	Assignment management
8	encoach_evaluation	evaluations.py	Evaluation results and AI jobs
9	encoach_stats	sessions.py, stats.py	Exam sessions and statistics
10	encoach_training	training.py	Training content, tips (FAISS), walkthroughs
11	encoach_classroom	classrooms.py	Classroom groups
12	encoach_subscription	subscriptions.py, discounts.py	Packages, payments, discounts
13	encoach_registration	registration.py	User registration, batch import
14	encoach_ticket	tickets.py	Support tickets
15	encoach_api	auth.py, users.py, entities.py, storage.py, approvals.py	REST API controllers (81+ endpoints)

1.2 Existing Endpoint Count by Group

Group	Estimated Count	Status
Auth (/api/login, /api/logout, etc.)	4	Built
Users (/api/user, /api/users/*)	6	Built
Entities & Roles (/api/entities, /api/roles, /api/permissions)	7	Built
Exams (/api/exam/*)	7	Built
AI Generation (/api/exam/*/generate)	12	Built
Media (/api/exam/*/media, /api/transcribe)	6	Built
Evaluations (/api/evaluate/*, /api/grading/*)	6	Built
Classrooms (/api/groups)	3	Built
Assignments (/api/assignments)	8	Built
Sessions & Stats (/api/sessions, /api/stats, /api/statistical)	5	Built
Training (/api/training/*)	4	Built
Subscriptions (/api/packages, /api/stripe, etc.)	7	Built
Registration (/api/register, /api/code/*)	4	Built
Tickets (/api/tickets)	3	Built
Storage (/api/storage)	2	Built
Approvals (/api/approval-workflows)	3	Built
TOTAL EXISTING	~87

---

2. What Needs to Be Built or Modified

2.1 New Endpoints Required (Frontend Expects These)

The frontend calls the following endpoints that do not exist yet. You must create them.

Group	Count	Priority
Taxonomy (subjects, domains, topics)	14	P0
Adaptive Learning (diagnostic, proficiency, learning plans)	16	P0
Resources (upload, manage, review)	7	P1
AI Coaching (chat, suggest, explain, tips)	6	P1
AI Utilities (search, insights, alerts, reports)	5	P2
Analytics (student, class, subject, content gaps)	4	P2
LMS Bridge (courses, batches, timetable, attendance, grades)	13	P1
TOTAL NEW	~65

2.2 Existing Modules Requiring Modification

Module	What to Change
encoach_exam	Add subject_id (Many2one to encoach.subject) and topic_ids (Many2many to encoach.topic) fields to encoach.exam model
encoach_stats	Add topic_id and subject_id fields to encoach.stat model
encoach_training	Add subject_id field to encoach.training.tip for per-subject FAISS indices
encoach_ai_generation	Extend prompts to support Math (include LaTeX/KaTeX formatting) and IT (code blocks, syntax) question types
encoach_ai_grading	Add grading logic for numerical-tolerance (Math) and keyword/pattern (IT) answers
encoach_subscription	Add subjects field to encoach.package for subject-scoped subscriptions
encoach_api	Add new controller files for all new endpoint groups

---

3. New Odoo Modules

Create these 8 new modules:

3.1 encoach_taxonomy

Purpose: Subject/domain/topic/learning-objective hierarchy.

Models:

Model	Key Fields
encoach.subject	name (Char), code (Char unique), is_active (Boolean), diagnostic_config (Text/JSON), mastery_threshold (Float default=80), grading_scale (Selection: percentage/band/letter), grading_scale_config (Text/JSON)
encoach.domain	name (Char), code (Char), subject_id (M2O encoach.subject), sequence (Integer)
encoach.topic	name (Char), code (Char), domain_id (M2O encoach.domain), estimated_hours (Float), difficulty_level (Selection: easy/medium/hard), prerequisite_ids (M2M self-ref), question_type_weights (Text/JSON)
encoach.learning.objective	name (Char), topic_id (M2O encoach.topic), bloom_level (Selection: remember/understand/apply/analyze/evaluate/create), sequence (Integer)

Computed fields on encoach.subject: domain_count, topic_count Computed fields on encoach.domain: topic_count Computed fields on encoach.topic: objective_count, prerequisite_names (list of names)

3.2 encoach_resources

Purpose: Human-uploaded learning materials tagged to topics.

Models:

Model	Key Fields
encoach.resource	name (Char), resource_type (Selection: pdf/video/link/document/interactive), url (Char), file (Binary), file_name (Char), topic_ids (M2M encoach.topic), author_id (M2O res.users), is_published (Boolean), review_status (Selection: pending/approved/rejected)
encoach.resource.completion	student_id (M2O res.users), resource_id (M2O encoach.resource), viewed (Boolean), time_spent_minutes (Integer), rating (Integer 1-5)

3.3 encoach_adaptive

Purpose: Core adaptive learning engine -- proficiency tracking, learning plans, content cache.

Models:

Model	Key Fields
encoach.proficiency	student_id (M2O res.users), topic_id (M2O encoach.topic), mastery (Float 0-100), mastery_level (Selection: not_started/beginner/developing/proficient/mastered -- computed from mastery), last_assessed (Datetime), time_spent_minutes (Integer)
encoach.learning.plan	student_id (M2O res.users), subject_id (M2O encoach.subject), status (Selection: active/paused/completed), ai_summary (Text), overall_progress (Float -- computed), target_completion (Date)
encoach.learning.plan.item	plan_id (M2O encoach.learning.plan), topic_id (M2O encoach.topic), sequence (Integer), status (Selection: locked/available/in_progress/completed), estimated_hours (Float), actual_hours (Float), mastery (Float -- from proficiency)
encoach.ai.content.cache	topic_id (M2O encoach.topic), content_type (Char), difficulty_level (Char), content (Text/JSON), model_used (Char), review_status (Selection: auto/reviewed/rejected)

Business logic:

• mastery_level is computed: 0-19 = not_started, 20-39 = beginner, 40-59 = developing, 60-79 = proficient, 80-100 = mastered
• overall_progress is computed from item statuses (completed_count / total_count * 100)
• When a plan item is completed, unlock the next item(s) based on prerequisite graph

3.4 encoach_adaptive_api

Purpose: REST controllers for the adaptive learning engine.

Controller files to create:

• taxonomy.py -- /api/subjects, /api/domains, /api/topics, /api/subjects/{id}/taxonomy
• resources.py -- /api/resources
• diagnostic.py -- /api/diagnostic/start, /api/diagnostic/answer, /api/diagnostic/{id}/result
• proficiency.py -- /api/proficiency, /api/proficiency/summary, /api/proficiency/class
• learning_plan.py -- /api/learning-plan, /api/learning-plan/generate, etc.
• content.py -- /api/topics/{id}/content, /api/topics/{id}/practice, /api/topics/{id}/mastery-quiz

3.5 encoach_adaptive_ai

Purpose: AI logic for diagnostics, plan generation, content generation, coaching.

Key services:

• Diagnostic question selection (adaptive difficulty algorithm)
• Learning plan generation (topological sort of topics by prerequisites, weighted by proficiency gaps)
• AI content generation for topics (call OpenAI GPT-4o with topic context)
• Practice question generation per topic
• Mastery quiz generation and grading
• Coaching: chat, hints, explanations, study suggestions, writing help, contextual tips

3.6 encoach_lms_api

Purpose: REST API bridge exposing OpenEduCat models to the frontend.

Controller files to create:

• courses.py -- /api/courses, /api/courses/{id}, /api/courses/ai-generate
• batches.py -- /api/batches, /api/batches/{id}
• timetable.py -- /api/timetable
• attendance.py -- /api/attendance
• grades.py -- /api/grades

Note: These controllers wrap the existing OpenEduCat Odoo models (op.course, op.batch, op.session, op.attendance.sheet, etc.) behind a clean REST API. Do NOT duplicate the models -- use the OpenEduCat models directly.

3.7 encoach_sis

Purpose: UTAS Student Information System integration.

Models:

• encoach.sis.sync -- sync job tracking (status, last_run, next_run, error_log)
• encoach.sis.mapping -- field mapping between SIS fields and EnCoach fields

3.8 encoach_branding

Purpose: Tenant whitelabeling.

Models:

• encoach.branding -- entity_id (M2O encoach.entity), logo (Binary), primary_color (Char), secondary_color (Char), font_family (Char)

---

4. Existing Module Modifications

4.1 encoach_exam -- Add Subject/Topic Fields

# In encoach_exam/models/exam.py, add:
subject_id = fields.Many2one('encoach.subject', string='Subject')
topic_ids = fields.Many2many('encoach.topic', string='Topics')
is_diagnostic = fields.Boolean(string='Is Diagnostic Exam', default=False)

4.2 encoach_stats -- Add Subject/Topic Fields

# In encoach_stats/models/stat.py, add:
subject_id = fields.Many2one('encoach.subject', string='Subject')
topic_id = fields.Many2one('encoach.topic', string='Topic')

4.3 encoach_training -- Add Subject Field

# In encoach_training/models/training_tip.py, add:
subject_id = fields.Many2one('encoach.subject', string='Subject')

4.4 encoach_subscription -- Add Subject Scoping

# In encoach_subscription/models/package.py, add:
subject_ids = fields.Many2many('encoach.subject', string='Included Subjects')

4.5 encoach_ai_generation -- Multi-Subject Prompts

Extend the generation prompts to handle:

• Math: Include LaTeX formatting instructions in prompts, numerical-tolerance answer checking
• IT: Include code block formatting, syntax highlighting hints, code-completion question types
• Generic: Accept subject_id and topic_id parameters, adjust prompt templates per subject

4.6 encoach_ai_grading -- Multi-Subject Grading

Extend grading logic:

• IELTS: Band scoring (existing)
• Math: Numerical tolerance (accept answers within +/- epsilon), step-by-step partial credit
• IT: Keyword matching, regex pattern matching, AI-graded code explanations

---

5. Complete API Contract

This is the definitive list of every endpoint the frontend calls. Each entry shows the HTTP method, path, request body (if POST/PATCH), and expected response shape. The TypeScript type files in encoach_frontend_new/src/types/ are the canonical response shapes.

5.1 Authentication (Existing -- auth.service.ts)

Method	Path	Request	Response
POST	/api/login	{ login: string, password: string }	{ token: string, user: User }
POST	/api/logout	--	void
GET	/api/user	--	User
POST	/api/reset/sendVerification	{ email: string }	{ success: boolean }

User shape: See src/types/auth.ts -- must include: id, name, email, login, user_type (one of: student/teacher/admin/corporate/mastercorporate/agent/developer), is_verified, entities (array of {id, name, role}), classrooms.

5.2 Users (Existing -- users.service.ts)

Method	Path	Request	Response
GET	/api/users/list	Query: type, entity_id, page, size, search, sort, order	PaginatedResponse<User>
GET	/api/users/{id}	--	User
PATCH	/api/users/update	{ id, ...fields }	User
POST	/api/users/create	Partial<User>	User
POST	/api/batch_users	{ users: Partial<User>[] }	{ success: boolean }

PaginatedResponse shape: { items: T[], total: number, page: number, size: number, pages: number }

5.3 Entities (Existing -- entities.service.ts)

Method	Path	Response
GET	/api/entities	PaginatedResponse<Entity>
GET	/api/entities/{id}	Entity
POST	/api/entities	Entity
PATCH	/api/entities/{id}	Entity
DELETE	/api/entities/{id}	{ success: boolean }
GET	/api/entities/{id}/roles	EntityRole[]
POST	/api/entities/{id}/roles	EntityRole
PATCH	/api/roles/{id}/permissions	EntityRole
GET	/api/permissions?entity_id=	string[] (list of permission keys for current user)

5.4 Exams (Existing -- exams.service.ts)

Method	Path	Response
GET	/api/exam/{module}	PaginatedResponse<Exam>
GET	/api/exam/{module}/{id}	Exam
POST	/api/exam	Exam
PATCH	/api/exam/{id}	Exam
DELETE	/api/exam/{id}	{ success: boolean }
PATCH	/api/exam/{id}/access	Exam
GET	/api/rubrics	PaginatedResponse<Rubric>
POST	/api/rubrics	Rubric
GET	/api/rubric-groups	PaginatedResponse<RubricGroup>
GET	/api/exam-structures	PaginatedResponse<ExamStructure>
POST	/api/exam-structures	ExamStructure
DELETE	/api/exam-structures/{id}	{ success: boolean }
GET	/api/exam/avatars	[{ id, name, thumbnail, voice }]

Note: Exam response must now include optional subject_id and topic_ids fields.

5.5 Assignments (Existing -- assignments.service.ts)

Method	Path	Response
GET	/api/assignments	PaginatedResponse<Assignment>
GET	/api/assignments/{id}	Assignment
POST	/api/assignments	Assignment
PATCH	/api/assignments/{id}	Assignment
DELETE	/api/assignments/{id}	{ success: boolean }
POST	/api/assignments/{id}/archive	Assignment
POST	/api/assignments/{id}/start	Assignment

5.6 Classrooms (Existing -- classrooms.service.ts)

Method	Path	Response
GET	/api/groups	PaginatedResponse<Classroom>
GET	/api/groups/{id}	Classroom
POST	/api/groups	Classroom
DELETE	/api/groups/{id}	{ success: boolean }
POST	/api/groups/transfer	{ success: boolean }
POST	/api/groups/{id}/members	{ success: boolean }
POST	/api/groups/{id}/members/remove	{ success: boolean }

5.7 Stats (Existing -- stats.service.ts)

Method	Path	Response
GET	/api/sessions	ExamSession[]
GET	/api/stats	ExamStat[]
GET	/api/statistical	StatisticalData
GET	/api/stats/performance	unknown[]

5.8 Evaluations (Existing -- evaluations.service.ts)

Method	Path	Request	Response
POST	/api/evaluate/writing	{ session_id, text, rubric_id? }	Evaluation
POST	/api/evaluate/speaking	{ session_id, audio_url, rubric_id? }	Evaluation
POST	/api/grading/multiple	{ session_id, answers: [{exercise_index, answer}] }	{ results: [{exercise_index, correct, score}] }
POST	/api/transcribe	FormData (audio file)	{ text: string }

5.9 Generation (Existing -- generation.service.ts)

Method	Path	Request	Response
POST	/api/exam/{module}/generate	{ title, label?, entity_id?, subject_id?, topic_id?, difficulty?, count? }	{ exam_id, exercises: [] }
POST	/api/exam/{module}/generate/scratch	Same as above	Same as above

Note: Must now accept subject_id and topic_id to scope generation to specific subjects/topics.

5.10 Training, Subscriptions, Tickets, Storage, Approvals (Existing)

These follow the existing patterns. See training.service.ts, subscriptions.service.ts, tickets.service.ts, storage.service.ts, approvals.service.ts for exact paths.

---

5.11 Taxonomy (NEW -- taxonomy.service.ts)

Method	Path	Request/Params	Response
GET	/api/subjects	--	Subject[]
GET	/api/subjects/{id}	--	Subject
POST	/api/subjects	Partial<Subject>	Subject
PATCH	/api/subjects/{id}	Partial<Subject>	Subject
DELETE	/api/subjects/{id}	--	{ success: boolean }
GET	/api/subjects/{id}/taxonomy	--	TaxonomyTree (nested: subject + domains + topics + objectives)
POST	/api/subjects/{id}/taxonomy/import	FormData (CSV/JSON)	{ success: boolean }
GET	/api/domains	Query: subject_id?	Domain[]
POST	/api/domains	Partial<Domain>	Domain
PATCH	/api/domains/{id}	Partial<Domain>	Domain
DELETE	/api/domains/{id}	--	{ success: boolean }
POST	/api/domains/{id}/ai-suggest	--	{ suggestions: Partial<Topic>[] }
GET	/api/topics	Query: domain_id?, subject_id?	Topic[]
POST	/api/topics	Partial<Topic>	Topic
PATCH	/api/topics/{id}	Partial<Topic>	Topic
DELETE	/api/topics/{id}	--	{ success: boolean }

TaxonomyTree shape:

{
  "subject": { "id": 1, "name": "IELTS", "code": "IELTS", ... },
  "domains": [
    {
      "id": 1, "name": "Writing", "code": "W", "sequence": 1,
      "topics": [
        {
          "id": 1, "name": "Task 1", "difficulty_level": "medium",
          "objectives": [
            { "id": 1, "name": "Describe trends", "bloom_level": "apply" }
          ]
        }
      ]
    }
  ]
}

5.12 Resources (NEW -- resources.service.ts)

Method	Path	Request/Params	Response
GET	/api/resources	Query: topic_id?, resource_type?, review_status?, page, size, search	PaginatedResponse<Resource>
POST	/api/resources	FormData (file + metadata)	Resource
PATCH	/api/resources/{id}	Partial<Resource>	Resource
DELETE	/api/resources/{id}	--	{ success: boolean }
POST	/api/resources/{id}/complete	--	ResourceCompletion
POST	/api/resources/{id}/rate	{ rating: number }	{ success: boolean }
GET	/api/resources/{id}/download	--	Binary file (stream)

5.13 Diagnostic Assessment (NEW -- adaptive.service.ts)

Method	Path	Request	Response
POST	/api/diagnostic/start	{ subject_id: number }	{ session: DiagnosticSession, first_question: DiagnosticQuestion }
POST	/api/diagnostic/answer	{ session_id, question_id, answer }	{ next_question?: DiagnosticQuestion, completed: boolean }
GET	/api/diagnostic/{id}/result	--	DiagnosticResult

DiagnosticQuestion shape:

{
  "id": "q_uuid",
  "topic_id": 5,
  "topic_name": "Line Graphs",
  "domain_name": "Writing",
  "difficulty": "medium",
  "question_type": "multiple_choice",
  "question_text": "Which of the following...",
  "options": ["A", "B", "C", "D"],
  "time_limit_seconds": 120
}

Diagnostic algorithm:

1. On /start: Create a diagnostic session. Pull topics from all domains. Start with starting_difficulty from subject's diagnostic_config.
2. On /answer: Grade the answer. If correct, increase difficulty and mastery estimate for that topic. If incorrect, decrease. Select the next question from a different domain/topic. Use Computer Adaptive Testing (CAT) principles.
3. Continue until total_question_cap reached or all domains have 2+ data points.
4. On completion: Write proficiency records for all assessed topics.

5.14 Proficiency (NEW -- adaptive.service.ts)

Method	Path	Params	Response
GET	/api/proficiency	Query: subject_id?	Proficiency[]
GET	/api/proficiency/summary	--	ProficiencySummary[]
GET	/api/proficiency/class	Query: subject_id?	Class-level aggregation

ProficiencySummary shape:

{
  "subject_id": 1,
  "subject_name": "IELTS",
  "overall_mastery": 65.5,
  "domain_scores": [{ "domain_id": 1, "domain_name": "Writing", "mastery": 72 }],
  "topics_mastered": 8,
  "topics_total": 20
}

5.15 Learning Plan (NEW -- adaptive.service.ts)

Method	Path	Request	Response
GET	/api/learning-plan	Query: subject_id	LearningPlan
POST	/api/learning-plan/generate	{ subject_id, target_completion? }	LearningPlan
PATCH	/api/learning-plan/{id}	Partial<LearningPlan>	LearningPlan
POST	/api/learning-plan/{id}/pause	--	LearningPlan
POST	/api/learning-plan/{id}/resume	--	LearningPlan

Plan generation algorithm:

1. Get student's proficiency records for the subject.
2. Identify topics below mastery threshold.
3. Topologically sort topics by prerequisites.
4. Create plan items in sequence. First item = available, rest = locked.
5. Call GPT-4o to generate ai_summary (natural language description of the plan).
6. Set estimated_hours from topic definitions.

5.16 Content Delivery (NEW -- adaptive.service.ts)

Method	Path	Request	Response
GET	/api/topics/{id}/content	--	TopicContent
POST	/api/topics/{id}/generate-content	--	TopicContent
POST	/api/topics/{id}/practice	--	{ questions: [] }
POST	/api/topics/{id}/practice/grade	{ answers: [] }	{ results: [], mastery_update: number }
POST	/api/topics/{id}/mastery-quiz	--	{ questions: [] }
POST	/api/topics/{id}/mastery-quiz/submit	{ answers: [] }	{ passed: boolean, score: number, mastery_update: number }

TopicContent shape:

{
  "topic_id": 5,
  "topic_name": "Line Graphs",
  "resources": [{ "id": 1, "name": "...", "resource_type": "pdf", "url": "..." }],
  "ai_content": {
    "explanation": "Line graphs show...",
    "examples": ["Example 1...", "Example 2..."],
    "key_points": ["Point 1", "Point 2"],
    "model_used": "gpt-4o"
  },
  "has_content_gap": true
}

has_content_gap = true when no human-uploaded resources exist for this topic, and AI content was generated to fill the gap.

5.17 AI Coaching (NEW -- coaching.service.ts)

Method	Path	Request	Response
POST	/api/coach/chat	{ message, context?: { page?, topic_id?, subject_id? }, history?: AiChatMessage[] }	{ message: string, suggestions?: string[] }
POST	/api/coach/hint	{ topic_id, question_id }	{ hint: string }
POST	/api/coach/explain	{ context, scores? }	{ explanation: string }
POST	/api/coach/suggest	{ subject_id? }	{ suggestions: string[], study_plan_tips: string[] }
POST	/api/coach/writing-help	{ text, task_type }	{ feedback, improved, grammar_notes: string[] }
GET	/api/coach/tip	Query: context	{ title, content, category }

All coaching endpoints use GPT-4o with appropriate system prompts.

5.18 AI Utilities (NEW -- analytics.service.ts)

Method	Path	Request	Response
POST	/api/ai/search	{ query }	AiSearchResult[]
POST	/api/ai/insights	{ data: {} }	AiInsight[]
GET	/api/ai/alerts	--	AiAlert[]
POST	/api/ai/report-narrative	{ report_type, data: {} }	{ narrative: string }
POST	/api/ai/batch-optimize	{ batch_id }	AiBatchOptimization[]
POST	/api/ai/grade-suggest	{ submission_id, text, rubric_id? }	AiGradingResult

5.19 Analytics (NEW -- analytics.service.ts)

Method	Path	Params	Response
GET	/api/analytics/student	Query params	Dashboard data
GET	/api/analytics/class	Query params	Class analytics
GET	/api/analytics/subject	Query params	Subject analytics
GET	/api/analytics/content-gaps	Query: subject_id?	{ gaps: [{ topic_id, topic_name, resource_count }] }

5.20 LMS Bridge (NEW -- lms.service.ts)

Method	Path	Request	Response
GET	/api/courses	Query: page, size, search, status	PaginatedResponse<Course>
GET	/api/courses/{id}	--	Course
POST	/api/courses	CourseCreateRequest	Course
PATCH	/api/courses/{id}	Partial<CourseCreateRequest>	Course
DELETE	/api/courses/{id}	--	{ success: boolean }
POST	/api/courses/ai-generate	{ title, subject_id?, level? }	{ outline: {} }
GET	/api/batches	Query: pagination	PaginatedResponse<Batch>
GET	/api/batches/{id}	--	Batch
POST	/api/batches	Partial<Batch>	Batch
PATCH	/api/batches/{id}	Partial<Batch>	Batch
DELETE	/api/batches/{id}	--	{ success: boolean }
GET	/api/timetable	Query: course_id?, teacher_id?, batch_id?	TimetableSession[]
POST	/api/timetable	Partial<TimetableSession>	TimetableSession
GET	/api/attendance	Query: course_id?, student_id?, date?	AttendanceRecord[]
POST	/api/attendance	{ course_id, date, records: [{student_id, status}] }	{ success: boolean }
GET	/api/grades	Query: course_id?, student_id?	GradeRecord[]

Course shape: See src/types/lms.ts -- must include: id, title, code, subject_id?, subject_name?, instructor_id, instructor_name, description, level, modules[], enrolled, max_capacity, status, start_date, end_date, progress?.

---

6. Data Model Specification

All data model details are in Section 30 of ENCOACH_UNIFIED_SRS.md (existing models: 30.1, new models: 30.2-30.4). Refer to that document for the complete field-level specification.

Key relationships:

Subject (1) → (N) Domain (1) → (N) Topic (1) → (N) LearningObjective
Topic (M) ↔ (M) Topic (prerequisites -- self-referencing M2M)
Topic (M) ↔ (M) Resource
Student (1) → (N) Proficiency (per topic)
Student (1) → (N) LearningPlan (per subject) → (N) LearningPlanItem (per topic)
Exam → Subject (optional M2O)
Exam → Topic[] (optional M2M)

---

7. AI Service Integration

The following external AI services are already configured (API keys in encoach_core/data/constants.xml and server .env):

Service	Purpose	Config Key
OpenAI GPT-4o	Content generation, grading, coaching, plan generation	encoach.openai_api_key
OpenAI GPT-3.5-turbo	Lightweight tasks (tips, search, suggestions)	Same key
OpenAI Whisper (local)	Speech-to-text	Local model
AWS Polly (Neural)	Text-to-speech for listening exams	encoach.aws_access_key_id, encoach.aws_secret_access_key
ELAI	AI avatar video generation	encoach.elai_api_key
GPTZero	AI writing detection	encoach.gptzero_api_key
FAISS + SentenceTransformers	Semantic similarity for training tips	Local model (all-MiniLM-L6-v2)

New AI tasks to implement:

Task	Model	Endpoint
Diagnostic question generation	GPT-4o	/api/diagnostic/start, /answer
Learning plan generation	GPT-4o	/api/learning-plan/generate
Topic content generation	GPT-4o	/api/topics/{id}/generate-content
Practice question generation	GPT-4o	/api/topics/{id}/practice
Mastery quiz generation	GPT-4o	/api/topics/{id}/mastery-quiz
AI coaching chat	GPT-4o	/api/coach/chat
Study suggestions	GPT-3.5-turbo	/api/coach/suggest
Writing feedback	GPT-4o	/api/coach/writing-help
Grade explanation	GPT-4o	/api/coach/explain
Contextual tips	GPT-3.5-turbo	/api/coach/tip
Semantic search	FAISS	/api/ai/search
Report narrative	GPT-4o	/api/ai/report-narrative
Data insights	GPT-4o	/api/ai/insights
Topic suggestion	GPT-4o	/api/domains/{id}/ai-suggest
Course outline generation	GPT-4o	/api/courses/ai-generate
Batch optimization	GPT-3.5-turbo	/api/ai/batch-optimize

---

8. Response Format Standards

8.1 Paginated Responses

All list endpoints that support pagination must return:

{
  "items": [...],
  "total": 150,
  "page": 1,
  "size": 20,
  "pages": 8
}

Query parameters: page (1-based), size (default 20), search (text filter), sort (field name), order (asc/desc).

8.2 Error Responses

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {}
}

HTTP status codes: 400 (validation), 401 (unauthorized), 403 (forbidden), 404 (not found), 500 (server error).

8.3 Success Responses

For write operations that don't return an entity:

{
  "success": true,
  "message": "Optional message"
}

8.4 JWT Token

• Token returned on login as { token: "...", user: {...} }
• Frontend sends Authorization: Bearer <token> on every request
• 401 response = token expired, frontend redirects to login

---

9. Non-Functional Requirements

Requirement	Specification
API response time (CRUD)	< 2 seconds
Diagnostic question generation	< 3 seconds
AI grading (writing/speaking)	< 60 seconds
Learning plan generation	< 10 seconds
AI content generation	< 15 seconds
Concurrent students per subject	200
Topics per subject	500
Resources per subject	1,000
Pagination on all list endpoints	Required
Server-side search/filter	Required
Soft delete for resources	Required (preserve completion records)
Proficiency weighted averages	Required (never direct overwrite)
Math content	LaTeX/KaTeX formatting in question text
IT content	Code blocks with language hints in question text

---

10. Implementation Priority

Phase	Modules	Endpoints	Estimated Effort
P0	encoach_taxonomy, modify encoach_exam/encoach_stats/encoach_training	Taxonomy CRUD (14), Subject/Topic fields on existing models	1 week
P1	encoach_adaptive, encoach_adaptive_api, encoach_adaptive_ai	Diagnostic (3), Proficiency (3), Learning Plan (5), Content (6)	2 weeks
P1	encoach_resources	Resource CRUD (7)	3 days
P1	encoach_lms_api	LMS bridge (13)	1 week
P2	encoach_adaptive_ai (coaching)	AI Coaching (6), AI Utilities (5)	1 week
P2	Analytics controllers	Analytics (4)	3 days
P3	encoach_sis, encoach_branding	SIS (4), Branding	1 week
P3	Multi-subject prompts/grading	Modify generation & grading modules	3 days
TOTAL	8 new modules + 7 modified	~65 new endpoints	~7 weeks

---

Appendix: File Handoff Checklist

File/Folder	Purpose	Location
This document	Backend SRS	ODOO_BACKEND_SRS_v3.md
Product SRS	Full platform specification	ENCOACH_UNIFIED_SRS.md
TypeScript types	Response shape contracts	encoach_frontend_new/src/types/*.ts
Service layer	Endpoint path contracts	encoach_frontend_new/src/services/*.ts
Existing modules	Already-built backend	ielts-be-v0/
Developer feedback	Review of existing work	ielts-be-v0/DEVELOPER_FEEDBACK.md
AI keys & config	Service credentials	ielts-be-v0/encoach_core/data/constants.xml

---

This document supersedes ODOO_MIGRATION_SRS_v2.md. The Odoo developer should treat this as the definitive backend specification. All endpoint paths, response shapes, and data models are aligned with the production frontend at encoach_frontend_new/.