encoach_backend_new_v2/new_project/SRS.md

Software Requirements Specification (SRS)

EnCoach — Adaptive Learning & LMS Platform

Field	Value
Document Version	1.0
Date	2026-03-28
Platform	EnCoach
Backend	Odoo 19 (Python 3.12) + PostgreSQL
Frontend	React 18 + TypeScript + Vite
Database	encoach_v2 (PostgreSQL 15+)

---

Table of Contents

1. Introduction
2. System Overview
3. User Roles & Access Control
4. Functional Requirements
5. Non-Functional Requirements
6. System Architecture
7. Data Models
8. API Specification
9. Frontend Pages & Routes
10. Third-Party Integrations
11. Deployment & Configuration
12. Appendices

---

1. Introduction

1.1 Purpose

This SRS documents the complete functional and technical requirements for the EnCoach platform — an adaptive learning and institutional LMS built on top of Odoo 19 and OpenEduCat. It serves as the single source of truth for development, QA, and deployment.

1.2 Scope

EnCoach is a multi-tenant, role-based educational platform that provides:

• Institutional LMS — courses, batches, students, teachers, timetables, attendance, grading, fees
• Adaptive Learning Engine — diagnostic tests, proficiency tracking, personalized learning plans, AI coaching
• AI-Powered Exam System — multi-module exams (Reading, Writing, Listening, Speaking), AI generation, AI grading
• Administrative Management — entities, roles, permissions, authority matrix, approval workflows
• Communication Suite — discussion boards, announcements, direct messaging, notifications
• Support & Training — FAQ, tickets, tips, walkthroughs
• Subscription & Payments — packages, Stripe/PayPal/Paymob integration

1.3 Definitions & Abbreviations

Term	Definition
Entity	An organization/institution using the platform (multi-tenant)
JWT	JSON Web Token — used for API authentication
OEC	OpenEduCat — the open-source education ERP built on Odoo
SPA	Single Page Application (the React frontend)
Taxonomy	Subject → Domain → Topic → Learning Objective hierarchy

---

2. System Overview

2.1 High-Level Architecture

┌──────────────────────────────────────────────────────┐
│                    Frontend (SPA)                     │
│    React 18 + TypeScript + Vite + shadcn/ui          │
│    Port: 8080 (dev) / static build (production)      │
└──────────────────┬───────────────────────────────────┘
                   │ REST API (/api/*)
                   │ JWT Bearer Token
┌──────────────────▼───────────────────────────────────┐
│                  Backend (Odoo 19)                    │
│    27 Custom Addons + OpenEduCat Modules              │
│    Port: 8069                                        │
├──────────────────┬───────────────────────────────────┤
│   PostgreSQL     │   External Services               │
│   encoach_v2     │   OpenAI, AWS Polly, Whisper,     │
│   Port: 5432     │   Stripe, PayPal, Paymob, ELAI   │
└──────────────────┴───────────────────────────────────┘

2.2 Technology Stack

Layer	Technology
Frontend Framework	React 18.3, TypeScript 5.6
Build Tool	Vite 5.4 with SWC
UI Components	shadcn/ui (Radix UI primitives + Tailwind CSS)
State Management	TanStack React Query v5 (server state), React Context (auth)
Forms	react-hook-form + zod validation
Charts	Recharts
Icons	Lucide React
Routing	React Router v6
Backend Framework	Odoo 19 (Python 3.12)
Base LMS	OpenEduCat ERP 19.0 (14 community + 21 enterprise modules)
Database	PostgreSQL 15+
Authentication	JWT (custom implementation via @jwt_required decorator)
API Style	REST over HTTP with JSON payloads

---

3. User Roles & Access Control

3.1 User Types

Role	Code	Description	Dashboard
Student	student	Enrolled learner; accesses courses, exams, adaptive learning	/student/dashboard
Teacher	teacher	Instructor; manages courses, assignments, attendance	/teacher/dashboard
Admin	admin	Full platform administrator	/admin/dashboard
Corporate	corporate	Entity-level manager	/admin/dashboard
Master Corporate	mastercorporate	Multi-entity manager	/admin/dashboard
Agent	agent	Sales/support agent	/admin/dashboard
Developer	developer	System developer with full access	/admin/dashboard

3.2 Permission System

• Roles — Defined per entity; each role has a set of permissions
• Permissions — Granular permissions with code, description, and category
• Authority Matrix — Cross-reference of roles × permissions, toggleable
• User-Level Overrides — Permissions can be assigned directly to users beyond their role
• Protected Routes — Frontend enforces allowedRoles and optional requiredPermissions

3.3 Authentication Flow

1. User submits email + password via POST /api/login
2. Backend validates credentials, returns JWT token + user profile
3. Token stored in localStorage as encoach_token
4. All subsequent API requests include Authorization: Bearer <token> header
5. On 401 response, token is cleared and user redirected to /login

---

4. Functional Requirements

4.1 Module: Authentication & User Management

ID	Requirement	Priority
FR-AUTH-01	Users can log in with email and password	Critical
FR-AUTH-02	Users can register with invite code or open registration	High
FR-AUTH-03	Password reset via email verification	High
FR-AUTH-04	JWT-based session management with automatic expiry	Critical
FR-AUTH-05	Admin can create, update, and export users	High
FR-AUTH-06	Batch user import from spreadsheet	Medium
FR-AUTH-07	Role-based access control with entity scoping	Critical

4.2 Module: Institutional LMS

ID	Requirement	Priority
FR-LMS-01	CRUD operations for Courses (title, code, capacity, status)	Critical
FR-LMS-02	CRUD operations for Batches linked to courses with date range	Critical
FR-LMS-03	CRUD operations for Students with portal user creation	Critical
FR-LMS-04	CRUD operations for Teachers with specialization	Critical
FR-LMS-05	Timetable management with day/time grid visualization	High
FR-LMS-06	Academic year and term management with auto-generation	High
FR-LMS-07	Department hierarchy with parent-child relationships	Medium
FR-LMS-08	Classroom management with capacity tracking	Medium
FR-LMS-09	Admission register workflow (create → confirm → close)	High
FR-LMS-10	Individual admission processing (submit → confirm → admit/reject)	High
FR-LMS-11	Lesson management linked to course, batch, and subject	High
FR-LMS-12	Attendance tracking per session	Medium
FR-LMS-13	Student leave management with approve/reject workflow	Medium
FR-LMS-14	Fees plan management (view plans, terms, student fees)	Medium
FR-LMS-15	Subject registration for students	Medium
FR-LMS-16	Library management (media, movements, student cards)	Low
FR-LMS-17	Facility and asset management	Low
FR-LMS-18	Student activity logging with activity types	Low

4.3 Module: Courseware & Content

ID	Requirement	Priority
FR-CW-01	Courses organized into ordered chapters	High
FR-CW-02	Chapters contain typed materials (video, PDF, document, interactive)	High
FR-CW-03	Chapter lock/unlock control by teachers	High
FR-CW-04	Material progress tracking (viewed, completed)	High
FR-CW-05	AI Workbench: generate course outline, chapter content, rubrics	Medium
FR-CW-06	Material reordering within chapters	Medium
FR-CW-07	Material download support	Medium

4.4 Module: Exam System

ID	Requirement	Priority
FR-EXAM-01	Multi-module exams: Reading, Writing, Listening, Speaking	Critical
FR-EXAM-02	Exam structures (blueprints) defining section layout	High
FR-EXAM-03	Rubrics and rubric groups for grading criteria	High
FR-EXAM-04	AI-powered exam generation from taxonomy	High
FR-EXAM-05	AI-powered grading for writing and speaking	High
FR-EXAM-06	Institutional exam sessions with scheduling workflow	High
FR-EXAM-07	Marksheet generation and validation	Medium
FR-EXAM-08	Grade configuration and result templates	Medium
FR-EXAM-09	Exam type management	Medium
FR-EXAM-10	Public/private exam access control with tokens	Medium
FR-EXAM-11	TTS audio generation for listening exams (AWS Polly)	Medium
FR-EXAM-12	STT transcription for speaking exams (Whisper)	Medium
FR-EXAM-13	Avatar-based speaking exam delivery (ELAI)	Low

4.5 Module: Assignments & Grading

ID	Requirement	Priority
FR-ASGN-01	Create assignments linked to exams with deadlines	High
FR-ASGN-02	Late submission with configurable penalty	Medium
FR-ASGN-03	Plagiarism checking and reports	Medium
FR-ASGN-04	Course-level assignments with submission workflow	High
FR-ASGN-05	Grading assignments (institutional grading system)	High
FR-ASGN-06	Gradebook view per student/course/academic year	High
FR-ASGN-07	Assignment type management	Medium

4.6 Module: Adaptive Learning

ID	Requirement	Priority
FR-ADAP-01	Subject taxonomy: Subject → Domain → Topic → Learning Objective	Critical
FR-ADAP-02	Diagnostic test to assess initial proficiency	High
FR-ADAP-03	Proficiency tracking per topic with mastery levels	High
FR-ADAP-04	AI-generated personalized learning plans	High
FR-ADAP-05	Topic-level adaptive content delivery	High
FR-ADAP-06	Practice exercises with AI grading	High
FR-ADAP-07	Mastery quizzes to unlock progression	Medium
FR-ADAP-08	AI domain suggestion for subjects	Medium
FR-ADAP-09	Taxonomy import/export	Medium
FR-ADAP-10	Class-level proficiency analytics	Medium

4.7 Module: AI Coaching

ID	Requirement	Priority
FR-AI-01	AI chat-based coaching assistant	High
FR-AI-02	Context-aware hints for exercises	Medium
FR-AI-03	Concept explanations on demand	Medium
FR-AI-04	Writing help and suggestions	Medium
FR-AI-05	Study tips generation	Low
FR-AI-06	AI report narratives for analytics	Medium
FR-AI-07	AI batch optimization suggestions	Low
FR-AI-08	AI grade suggestions	Low
FR-AI-09	AI-powered content gap analysis	Low

4.8 Module: Communication

ID	Requirement	Priority
FR-COMM-01	Discussion boards with posts, pinning, and resolving	High
FR-COMM-02	Announcements with publish workflow	High
FR-COMM-03	Direct messaging between users	High
FR-COMM-04	Unread message count indicators	Medium
FR-COMM-05	In-app notification system	High
FR-COMM-06	Notification rules (event type, days before, frequency, channel)	Medium
FR-COMM-07	User notification preferences (in-app / email / both)	Medium

4.9 Module: Entity & Role Management

ID	Requirement	Priority
FR-ENT-01	Multi-tenant entity management (create, update, delete)	Critical
FR-ENT-02	Entity-scoped roles and permissions	Critical
FR-ENT-03	Authority matrix visualization and configuration	High
FR-ENT-04	User-to-role assignment and toggle	High
FR-ENT-05	Invite code generation for entity onboarding	Medium
FR-ENT-06	Per-entity branding/whitelabeling	Low

4.10 Module: Subscription & Payments

ID	Requirement	Priority
FR-PAY-01	Subscription packages with pricing and features	High
FR-PAY-02	Stripe checkout integration	High
FR-PAY-03	PayPal checkout integration	Medium
FR-PAY-04	Paymob checkout integration	Medium
FR-PAY-05	Webhook processing for payment confirmation	High
FR-PAY-06	Discount codes and management	Medium
FR-PAY-07	Payment history tracking	Medium

4.11 Module: Support & Training

ID	Requirement	Priority
FR-SUP-01	FAQ category and item management (CRUD)	High
FR-SUP-02	Public FAQ page with audience filtering	Medium
FR-SUP-03	Support ticket creation and management	High
FR-SUP-04	Ticket assignment to support agents	Medium
FR-SUP-05	Training tips and walkthroughs	Low

4.12 Module: Approval Workflows

ID	Requirement	Priority
FR-APPR-01	Configurable multi-stage approval workflows	Medium
FR-APPR-02	Approval request submission and tracking	Medium
FR-APPR-03	Approve, reject, bypass, and return actions	Medium
FR-APPR-04	Auto-escalation after max days	Low

4.13 Module: Reports & Analytics

ID	Requirement	Priority
FR-RPT-01	Platform dashboard with real-time statistics from database	High
FR-RPT-02	LMS dashboard with course/batch/student/teacher counts	High
FR-RPT-03	Course enrollment and capacity charts	Medium
FR-RPT-04	Student status distribution	Medium
FR-RPT-05	Analytics: student, class, subject, content gaps	Medium
FR-RPT-06	CSV data export	Medium
FR-RPT-07	Student progress tracking across courses	Medium

4.14 Module: Resource Management

ID	Requirement	Priority
FR-RES-01	Upload learning resources (PDF, video, link, document, interactive)	High
FR-RES-02	Resource review workflow (pending → approved/rejected)	Medium
FR-RES-03	Resource download, completion tracking, and rating	Medium
FR-RES-04	Topic-linked resource tagging	Medium

---

5. Non-Functional Requirements

ID	Category	Requirement
NFR-01	Performance	API response time < 2s for list endpoints with pagination
NFR-02	Performance	Frontend initial load < 3s on broadband connections
NFR-03	Scalability	Support 500+ concurrent users per entity
NFR-04	Security	JWT tokens with expiry; HTTPS required in production
NFR-05	Security	CSRF protection on all state-changing endpoints
NFR-06	Security	Password hashing via Odoo's PBKDF2-SHA512
NFR-07	Security	Role-based access enforced on both frontend and backend
NFR-08	Availability	99.5% uptime SLA target
NFR-09	Compatibility	Chrome 90+, Firefox 90+, Safari 15+, Edge 90+
NFR-10	Responsive	Mobile-friendly responsive design via Tailwind CSS
NFR-11	i18n	Odoo's built-in JSONB translatable fields (en_US default)
NFR-12	Data Integrity	Foreign key constraints with proper cascade/restrict rules
NFR-13	API Design	RESTful conventions; JSON responses; proper HTTP status codes
NFR-14	Error Handling	User-friendly error messages; 409 for FK violations; 400 for validation

---

6. System Architecture

6.1 Backend Module Architecture

The backend consists of 27 custom Odoo addons organized by domain:

Domain	Addons
Core	encoach_core (entities, roles, permissions, users)
API Layer	encoach_api, encoach_lms_api, encoach_adaptive_api, encoach_resources
Exam Engine	encoach_exam (structures, rubrics, sessions, evaluation)
Assignments	encoach_assignment (exam-linked assignments, extensions)
Adaptive Learning	encoach_taxonomy, encoach_adaptive (proficiency, plans, diagnostics)
AI Services	encoach_ai, encoach_ai_grading, encoach_ai_generation, encoach_ai_media, encoach_adaptive_ai
Courseware	encoach_courseware (chapters, materials, progress, AI workbench)
Communication	encoach_communication (boards, posts, DMs, announcements)
Subscription	encoach_subscription (packages, payments, discounts)
Notifications	encoach_notification (rules, preferences, delivery)
Approval	encoach_approval (workflows, stages, requests)
Support	encoach_ticket, encoach_faq, encoach_training
Other	encoach_classroom, encoach_registration, encoach_branding, encoach_stats, encoach_sis, encoach_resources

6.2 OpenEduCat Foundation

Community Modules (14): openeducat_core, openeducat_admission, openeducat_assignment, openeducat_attendance, openeducat_classroom, openeducat_exam, openeducat_timetable, openeducat_library, openeducat_activity, openeducat_fees, openeducat_facility, openeducat_parent, openeducat_erp, theme_web_openeducat

Enterprise Modules (21): openeducat_core_enterprise, openeducat_web, openeducat_onboarding, openeducat_admission_enterprise, openeducat_dynamic_admission, openeducat_assignment_enterprise, openeducat_assignment_grading_enterprise, openeducat_assignment_grading_bridge, openeducat_exam_enterprise, openeducat_grading, openeducat_classroom_enterprise, openeducat_lesson, openeducat_timetable_enterprise, openeducat_attendance_enterprise, openeducat_attendance_report_xlsx, openeducat_student_leave_enterprise, openeducat_student_progress_enterprise, openeducat_fees_plan, openeducat_fees_on_session, openeducat_fees_on_duration, openeducat_core_send_mail

6.3 Frontend Architecture

src/
├── components/          # Shared UI components
│   ├── ui/              # shadcn/ui primitives (50+ components)
│   ├── ai/              # AI feature components (14 components)
│   ├── layouts/         # AppLayout, AdminLmsLayout, StudentLayout, TeacherLayout
│   └── ProtectedRoute   # Role-based route guard
├── contexts/            # AuthContext (user state, login/logout)
├── hooks/
│   ├── queries/         # TanStack Query hooks (useCourses, useStudents, etc.)
│   └── usePermissions   # Permission checking hook
├── lib/
│   ├── api-client.ts    # HTTP client with JWT, base URL, 401 handling
│   └── query-client.ts  # TanStack Query configuration
├── pages/
│   ├── admin/           # 33 admin page components
│   ├── student/         # 19 student page components
│   ├── teacher/         # 14 teacher page components
│   └── (auth pages)     # Login, Register, ForgotPassword, etc.
├── services/            # API service modules (30+ service files)
└── types/               # TypeScript interfaces (20+ type files)

---

7. Data Models

7.1 Custom EnCoach Models

Model	Key Fields	Purpose
encoach.entity	name, code, type, logo, active, user_ids, role_ids	Multi-tenant organization
encoach.role	name, entity_id, permission_ids, user_ids, description	Role within an entity
encoach.permission	name, code, description, category	Granular permission
encoach.invite.code	code, entity_id, role_id, user_type, max_uses, expires_at	Invite-based registration
encoach.subject	name, code, mastery_threshold, grading_scale, diagnostic_config	Taxonomy root
encoach.domain	name, subject_id	Taxonomy level 2
encoach.topic	name, domain_id, difficulty	Taxonomy level 3
encoach.learning.objective	name, topic_id	Taxonomy level 4
encoach.exam	name, module, subject_id, topic_ids, structure_id, rubric_id, exercises, passages, difficulty, time_limit, status	AI-powered exam
encoach.exam.structure	name, sections	Exam blueprint
encoach.exam.rubric	name, criteria	Grading rubric
encoach.exam.session	exam_id, user_id, score, answers, started_at, completed_at	Exam attempt
encoach.assignment	name, exam_id, entity_id, assignee_ids, deadline, late_deadline, penalties	Exam wrapper
encoach.diagnostic.session	user_id, subject_id, result, status	Diagnostic test session
encoach.proficiency	user_id, topic_id, level, score	Proficiency tracking
encoach.learning.plan	user_id, subject_id, items, status	Personalized plan
encoach.course.chapter	course_id, name, sequence, is_locked	Course chapter
encoach.chapter.material	chapter_id, name, type, sequence, file/url	Chapter content
encoach.chapter.progress	user_id, chapter_id, material_id, completed	Progress tracking
encoach.discussion.board	name, entity_id, course_id	Discussion forum
encoach.discussion.post	board_id, author_id, content, is_pinned, is_resolved	Forum post
encoach.direct.message	sender_id, recipient_id, content	Direct message
encoach.announcement	title, content, entity_id, is_published	Announcement
encoach.notification	user_id, title, message, type, is_read	In-app notification
encoach.notification.rule	name, event_type, days_before, frequency, channel	Notification rule
encoach.ticket	subject, description, type, status, reporter_id, assignee_id	Support ticket
encoach.faq.category	name, audience, item_count	FAQ category
encoach.faq.item	question, answer, category_id, audience, sequence	FAQ item
encoach.package	name, price, currency, duration_days, features	Subscription package
encoach.payment	user_id, package_id, amount, status, provider	Payment record
encoach.discount	code, percentage, valid_from, valid_to	Discount code
encoach.approval.workflow	name, entity_id, status, steps	Approval workflow
encoach.approval.request	workflow_id, requester_id, status	Approval request
encoach.resource	name, resource_type, review_status, topic_ids, author_id	Learning resource
encoach.branding	entity_id, logo, primary_color, favicon	Per-entity branding
encoach.classroom.group	name, entity_id, member_ids	Virtual classroom group
encoach.training.tip	title, content, context	Training tip
encoach.training.walkthrough	title, steps	Training walkthrough

7.2 Extended OpenEduCat Models

Model	Extensions Added
res.users	user_type, is_verified, entity_ids, role_ids, permission_direct_ids, op_student_id, op_faculty_id
op.course	Additional fields via encoach_lms_api
op.student	Extended with portal user link
op.faculty	Extended with specialization
op.batch	Extended with capacity/status
op.subject	Extended for taxonomy link

7.3 Core OpenEduCat Models (Used As-Is)

op.course, op.batch, op.student, op.faculty, op.subject, op.session, op.classroom, op.department, op.exam, op.exam.session, op.exam.attendees, op.exam.type, op.grade.configuration, op.result.template, op.marksheet.register, op.academic.year, op.academic.term, op.admission, op.admission.register, op.lesson, op.attendance, op.attendance.line, op.fees.plan, op.fees.term, op.library.media, op.media.movement, op.student.course, op.student.leave

---

8. API Specification

8.1 Authentication

Method	Endpoint	Description
POST	/api/login	Authenticate user, returns JWT
POST	/api/logout	Invalidate session
GET	/api/user	Get current user profile
POST	/api/reset/sendVerification	Send password reset email

8.2 LMS Core

Method	Endpoint	Description
GET/POST	/api/courses	List / create courses
GET/PATCH/DELETE	/api/courses/<id>	Read / update / delete course
GET/POST	/api/students	List / create students
GET/PATCH/DELETE	/api/students/<id>	Read / update / delete student
GET/POST	/api/teachers	List / create teachers
PATCH/DELETE	/api/teachers/<id>	Update / delete teacher
GET/POST	/api/batches	List / create batches
PATCH/DELETE	/api/batches/<id>	Update / delete batch
GET/POST/DELETE	/api/classrooms	Classrooms CRUD
GET/POST	/api/lessons	List / create lessons
PATCH/DELETE	/api/lessons/<id>	Update / delete lesson
GET/POST	/api/timetable	List / create sessions
DELETE	/api/timetable/<id>	Delete session
GET/POST	/api/attendance	Attendance
GET/POST/PATCH/DELETE	/api/departments	Departments CRUD
GET/POST/DELETE	/api/academic-years	Academic years
GET/POST	/api/academic-terms	Terms
POST	/api/academic-years/<id>/generate-terms	Auto-generate terms

8.3 Admissions

Method	Endpoint	Description
GET/POST	/api/admission-registers	Registers
POST	/api/admission-registers/<id>/confirm	Confirm register
POST	/api/admission-registers/<id>/close	Close register
GET/POST	/api/admissions	Applications
POST	/api/admissions/<id>/submit|confirm|admit|reject	Workflow actions

8.4 Exams & Grading

Method	Endpoint	Description
GET	/api/exam/<module>	List exams by module
GET	/api/exam/<module>/<id>	Exam detail
POST	/api/exam	Create exam
PATCH/DELETE	/api/exam/<id>	Update / delete exam
GET/POST	/api/exam-structures	Structures CRUD
GET/POST	/api/rubrics	Rubrics CRUD
GET/POST	/api/inst-exam-sessions	Institutional sessions
PATCH/DELETE	/api/inst-exam-sessions/<id>	Update / delete session
POST	/api/inst-exam-sessions/<id>/schedule|done	Workflow
GET/POST	/api/exam-types	Exam types
GET	/api/grade-config	Grade configuration
GET/POST	/api/result-templates	Result templates
GET	/api/marksheets	Marksheets
POST	/api/marksheets/validate	Validate marksheet
GET/POST/PATCH/DELETE	/api/grading-assignments	Grading assignments
GET	/api/gradebooks	Gradebooks
GET/POST/PATCH	/api/assignment-types	Assignment types

8.5 Adaptive Learning

Method	Endpoint	Description
GET/POST/PATCH/DELETE	/api/subjects	Taxonomy subjects
GET/POST/PATCH/DELETE	/api/domains	Domains
GET/POST/PATCH/DELETE	/api/topics	Topics
POST	/api/diagnostic/start	Start diagnostic
POST	/api/diagnostic/answer	Submit answer
GET	/api/diagnostic/<id>/result	Get result
GET	/api/proficiency	User proficiency
GET	/api/proficiency/summary	Summary
GET	/api/proficiency/class	Class-level
GET/POST/PATCH	/api/learning-plan	Learning plans

8.6 AI Services

Method	Endpoint	Description
POST	/api/exam/<module>/generate	AI exam generation
POST	/api/exam/<module>/generate/scratch	Generate from scratch
POST	/api/evaluate/writing	AI writing evaluation
POST	/api/evaluate/speaking	AI speaking evaluation
POST	/api/grading/multiple	Bulk AI grading
POST	/api/transcribe	Speech-to-text
POST	/api/coach/chat|hint|explain|suggest	AI coaching
POST	/api/ai/insights|search|report-narrative	AI analytics
POST	/api/workbench/generate-outline|generate-chapter	AI courseware

8.7 Communication

Method	Endpoint	Description
GET/POST/PATCH/DELETE	/api/discussion-boards	Boards
GET/POST	/api/discussion-boards/<id>/posts	Posts
PATCH/DELETE	/api/posts/<id>	Update/delete post
GET/POST/PATCH/DELETE	/api/announcements	Announcements
GET/POST	/api/messages	Direct messages
GET	/api/notifications	List notifications
GET/POST/PATCH/DELETE	/api/notification-rules	Rules

8.8 Entities, Roles, Permissions

Method	Endpoint	Description
GET/POST/PATCH/DELETE	/api/entities	Entities
GET/POST/PATCH/DELETE	/api/roles	Roles
PATCH	/api/roles/<id>/permissions	Set permissions
GET/POST/DELETE	/api/permissions	Permissions
GET	/api/authority-matrix	Authority matrix
POST	/api/authority-matrix/toggle	Toggle permission
GET	/api/users/with-roles	Users with role data

8.9 Support & Payments

Method	Endpoint	Description
GET/POST/PATCH/DELETE	/api/faq/categories	FAQ categories
GET/POST/PATCH/DELETE	/api/faq/items	FAQ items
GET/POST/PATCH	/api/tickets	Support tickets
GET	/api/packages	Subscription packages
POST	/api/stripe/checkout	Stripe checkout
POST	/api/paypal/checkout	PayPal checkout
POST	/api/paymob/checkout	Paymob checkout
POST	/api/stripe/webhook	Stripe webhook (no JWT)
GET/POST/DELETE	/api/discounts	Discounts
GET/POST	/api/resources	Learning resources
PATCH/DELETE	/api/resources/<id>	Update/delete resource
GET/POST/PATCH/DELETE	/api/approval-workflows	Approval workflows
GET/POST	/api/student-leaves	Student leave requests
GET	/api/fees-plans	Fees plans
GET	/api/student-progress	Student progress
GET	/api/stats	Platform statistics

---

9. Frontend Pages & Routes

9.1 Public Pages (No Authentication)

Route	Page	Purpose
/login	Login	User authentication
/register	Register	New user registration
/forgot-password	ForgotPassword	Password reset
/apply	AdmissionApplication	Public admission form
/faq	FaqPage	Public FAQ
/exam/access/:token	OfficialExamAccess	Token-based exam access

9.2 Student Pages (19 pages)

Route	Page	CRUD
/student/dashboard	StudentDashboard	R
/student/courses	StudentCourses	R
/student/courses/:id	StudentCourseDetail	R
/student/courses/:id/chapters/:chapterId	StudentChapterView	R
/student/assignments	StudentAssignments	R
/student/grades	StudentGrades	R
/student/attendance	StudentAttendance	R
/student/timetable	StudentTimetable	R
/student/profile	StudentProfile	RU
/student/subjects	SubjectSelection	R
/student/diagnostic/:subjectId	DiagnosticTest	CR
/student/proficiency/:subjectId	ProficiencyProfile	R
/student/plan/:subjectId	LearningPlanPage	CR
/student/topic/:topicId	TopicLearning	R
/student/subject-registration	SubjectRegistrationPage	CR
/student/discussions	StudentDiscussionBoard	CRD
/student/announcements	StudentAnnouncements	R
/student/messages	StudentMessages	CR
/student/journey	StudentJourney	R

9.3 Teacher Pages (14 pages)

Route	Page	CRUD
/teacher/dashboard	TeacherDashboard	R
/teacher/courses	TeacherCourses	R
/teacher/courses/new	CourseBuilder	C
/teacher/courses/:id/edit	CourseBuilder	U
/teacher/courses/:id/chapters	CourseChapters	CRUD
/teacher/courses/:id/chapters/:chapterId	ChapterDetail	RU
/teacher/courses/:id/workbench	AiWorkbench	C
/teacher/assignments	TeacherAssignments	CRUD
/teacher/assignments/:id	TeacherAssignmentDetail	RU
/teacher/attendance	TeacherAttendance	CR
/teacher/students	TeacherStudents	R
/teacher/timetable	TeacherTimetable	R
/teacher/discussions	TeacherDiscussionBoard	CRUD
/teacher/announcements	TeacherAnnouncements	CRUD
/teacher/profile	TeacherProfile	RU

9.4 Admin Pages (53 pages)

Route	Page	CRUD
/admin/dashboard	AdminLmsDashboard	R
/admin/platform	AdminDashboard	R
/admin/courses	AdminCourses	CRD
/admin/students	AdminStudents	CRD
/admin/teachers	AdminTeachers	CRD
/admin/batches	AdminBatches	CRD
/admin/batches/:id	AdminBatchDetail	R
/admin/timetable	AdminTimetable	CRD
/admin/reports	AdminReports	R
/admin/settings	AdminSettings	RU
/admin/profile	AdminProfile	RU
/admin/taxonomy	TaxonomyManager	CRD
/admin/resources	ResourceManager	CRD
/admin/academic-years	AcademicYearManager	CRD
/admin/departments	DepartmentManager	CRUD
/admin/admissions	AdmissionList	R
/admin/admissions/:id	AdmissionDetail	RU
/admin/admission-register	AdmissionRegisterPage	CR
/admin/exam-sessions	InstitutionalExamSessions	CR
/admin/marksheets	MarksheetManager	CR
/admin/student-leave	AdminStudentLeave	CR
/admin/fees	AdminFees	R
/admin/lessons	AdminLessons	CRUD
/admin/gradebook	AdminGradebook	CRUD
/admin/student-progress	AdminStudentProgress	R
/admin/library	AdminLibrary	CRD
/admin/activities	AdminActivities	CRD
/admin/facilities	AdminFacilities	CRD
/admin/faq	FaqManager	CRUD
/admin/notification-rules	NotificationRules	CRUD
/admin/approval-config	ApprovalWorkflowConfig	CRD
/admin/roles-permissions	RolesPermissions	CRUD
/admin/authority-matrix	AuthorityMatrix	RU
/admin/user-roles	UserRoles	RU
/admin/assignments	AssignmentsPage	CRUD
/admin/examsList	ExamsListPage	CRUD
/admin/exam-structures	ExamStructuresPage	CRD
/admin/rubrics	RubricsPage	CRD
/admin/generation	GenerationPage	C
/admin/approval-workflows	ApprovalWorkflowsPage	CRUD
/admin/users	UsersPage	CRUD
/admin/entities	EntitiesPage	CRUD
/admin/classrooms	ClassroomsPage	CRUD
/admin/student-performance	StudentPerformancePage	R
/admin/stats-corporate	StatsCorporatePage	R
/admin/tickets	TicketsPage	CRUD
/admin/settings-platform	SettingsPage	RU
/admin/exam	ExamPage	CRUD
/admin/record	RecordPage	R
/admin/training/vocabulary	VocabularyPage	R
/admin/training/grammar	GrammarPage	R
/admin/payment-record	PaymentRecordPage	R

---

10. Third-Party Integrations

Service	Purpose	Integration Point
OpenAI (GPT-4o)	Exam generation, AI grading, coaching, content creation	encoach_ai, encoach_ai_grading, encoach_ai_generation, encoach_adaptive_ai
AWS Polly	Text-to-speech for listening exams	encoach_ai_media
OpenAI Whisper	Speech-to-text for speaking exams	encoach_ai_media
ELAI	AI avatar video generation	encoach_ai_media
GPTZero	Plagiarism/AI content detection	encoach_assignment
Stripe	Payment processing	encoach_subscription (webhooks)
PayPal	Payment processing	encoach_subscription (webhooks)
Paymob	Payment processing (MENA region)	encoach_subscription (webhooks)
UTAS SIS	Student Information System integration	encoach_sis

---

11. Deployment & Configuration

11.1 Environment Configuration

Variable	Default	Description
VITE_API_BASE_URL	/api	Backend API base URL
VITE_APP_NAME	EnCoach	Application display name
db_name	encoach_v2	PostgreSQL database name
http_port	8069	Odoo backend port
Dev server port	8080	Vite dev server port

11.2 Backend Configuration (odoo.conf)

[options]
db_user = <db_user>
db_host = localhost
db_port = 5432
db_name = encoach_v2
http_interface = 127.0.0.1
http_port = 8069
addons_path = custom_addons,enterprise-19,openeducat_erp-19.0,odoo/addons
workers = 0  (development) / 4+ (production)
limit_time_cpu = 600
limit_time_real = 1200

11.3 Prerequisites

Component	Version
Python	3.12+
Node.js	18+
PostgreSQL	15+
Odoo	19.0

11.4 Development Setup

1. Clone repository
2. Create Python virtual environment and install Odoo dependencies
3. Create PostgreSQL database encoach_v2
4. Configure new_project/odoo.conf with database credentials
5. Start Odoo: python3 odoo/odoo-bin -c new_project/odoo.conf
6. Install Node.js dependencies: cd new_project/encoach_frontend_new_v1 && npm install
7. Start frontend: npm run dev (available at http://localhost:8080)
8. Vite proxy forwards /api/* to Odoo at port 8069

---

12. Appendices

Appendix A: Module Count Summary

Category	Count
Custom Odoo Addons	27
OpenEduCat Community Modules	14
OpenEduCat Enterprise Modules	21
Custom Odoo Models	45+
REST API Endpoints	200+
Frontend Pages (Total)	90+
Frontend Pages — Admin	53
Frontend Pages — Student	19
Frontend Pages — Teacher	14
Frontend Pages — Public	6
Service Files	30+
TypeScript Type Files	20+
UI Components (shadcn)	50+
AI Feature Components	14

Appendix B: Tested API Endpoints (CRUD Verification)

All core CRUD operations have been tested and verified (59/59 pass rate):

• CREATE: Courses, Students, Teachers, Batches, Entities, Classrooms, Subjects, Timetable, Academic Years, Departments, Roles, Lessons, FAQ Categories
• READ: All 35+ list endpoints verified (200 OK)
• DELETE: Courses, Students, Teachers, Batches, Entities, Classrooms, Subjects, Timetable, Academic Years, Departments, Roles, Lessons, FAQ Categories
• UPDATE: Courses, Teachers, Entities, Departments, Lessons, Notification Rules, FAQ Items

Appendix C: Delete Confirmation Coverage

All destructive operations on the frontend include window.confirm() dialogs: Courses, Students, Teachers, Batches, Entities, Departments, Academic Years, Timetable Sessions, Resources, FAQ Categories, FAQ Items, Approval Workflows, Notification Rules, Activities, Activity Types, Facilities, Lessons, Gradebook Assignments, Classrooms, Roles

---

End of SRS Document