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](#1-introduction)
2. [System Overview](#2-system-overview)
3. [User Roles & Access Control](#3-user-roles--access-control)
4. [Functional Requirements](#4-functional-requirements)
5. [Non-Functional Requirements](#5-non-functional-requirements)
6. [System Architecture](#6-system-architecture)
7. [Data Models](#7-data-models)
8. [API Specification](#8-api-specification)
9. [Frontend Pages & Routes](#9-frontend-pages--routes)
10. [Third-Party Integrations](#10-third-party-integrations)
11. [Deployment & Configuration](#11-deployment--configuration)
12. [Appendices](#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*