diff --git a/README.md b/README.md index 77517565..f2bd2109 100644 --- a/README.md +++ b/README.md @@ -1,140 +1,123 @@ -# EnCoach Backend — v2 +# EnCoach Backend v2 — Odoo 19 Adaptive Learning Platform + +The Odoo 19 backend for the **EnCoach** adaptive learning and institutional LMS platform. Provides ~377 REST API endpoints serving a React 18 SPA frontend. + +## System Overview + +| Component | Detail | +|-----------|--------| +| **Framework** | Odoo 19 Community Edition | +| **Language** | Python 3.12+ | +| **Database** | PostgreSQL 16 | +| **LMS Foundation** | OpenEduCat Community (14 modules, ported to v19) | +| **Custom Modules** | 27 `encoach_*` modules | +| **AI/ML** | OpenAI GPT-4o, Whisper (local), AWS Polly, ELAI, GPTZero, FAISS | +| **Authentication** | JWT (PyJWT) | +| **Deployment** | Docker Compose | + +## Module Architecture + +``` +new_project/ + custom_addons/ # 27 custom EnCoach modules + encoach_api/ # REST API controllers (~120 routes) + encoach_lms_api/ # OpenEduCat bridge API (~209 routes) + encoach_adaptive_api/ # Adaptive learning API (~41 routes) + encoach_resources/ # Resource library API (~7 routes) + encoach_core/ # Users, entities, roles, permissions + encoach_taxonomy/ # Subject > Domain > Topic taxonomy + encoach_adaptive/ # Proficiency, learning plans, mastery + encoach_adaptive_ai/ # AI for diagnostics, coaching, content + encoach_exam/ # AI-powered exam engine + encoach_ai/ # OpenAI service wrapper + encoach_ai_generation/ # AI exam content generation + encoach_ai_grading/ # AI grading (writing, speaking, math, IT) + encoach_ai_media/ # TTS (Polly), STT (Whisper), ELAI avatars + encoach_courseware/ # Chapters, materials, AI workbench + encoach_communication/ # Discussion boards, announcements, messaging + encoach_notification/ # Notification engine, rules, preferences + encoach_faq/ # FAQ categories and items + encoach_approval/ # Approval workflows, stages + encoach_assignment/ # Exam-wrapper assignments + encoach_classroom/ # Virtual classroom groups + encoach_stats/ # Session tracking, statistics + encoach_training/ # Training tips, walkthroughs, FAISS + encoach_subscription/ # Packages, Stripe/PayPal/Paymob + encoach_registration/ # User registration, batch import + encoach_ticket/ # Support tickets + encoach_sis/ # UTAS SIS integration + encoach_branding/ # Whitelabeling + openeducat_erp-19.0/ # 14 OpenEduCat community modules + openeducat_core/ # Courses, batches, students, faculty + openeducat_timetable/ # Timetable sessions + openeducat_attendance/ # Attendance management + openeducat_exam/ # Institutional exams, marksheets + openeducat_assignment/ # Course assignments, submissions + openeducat_admission/ # Admission registers, applications + openeducat_classroom/ # Physical classrooms + openeducat_facility/ # Facilities and assets + openeducat_fees/ # Fee plans, student fees + openeducat_library/ # Library media, movements, cards + openeducat_activity/ # Student activities + openeducat_parent/ # Parent-student relationships + openeducat_erp/ # ERP connector + theme_web_openeducat/ # Web theme +``` + +## Staging + +| Service | URL | +|---------|-----| +| **Odoo Backend** | `http://5.189.151.117:8069` | +| **React Frontend** | `http://5.189.151.117:3000` | ## Branching Workflow This repo is connected to the staging server via a Git post-receive hook. -**All deployment is automatic — but only after code review approval.** +**All deployment is automatic after code review approval.** -### How to contribute - -1. Never push directly to `main` — branch protection will block it. -2. Push your changes to your feature branch (e.g. `feature/full-backend-v1`) -3. Open a Pull Request on Gitea targeting `main` -4. Request review from **devops (Talal)** +1. Never push directly to `main` -- branch protection will block it. +2. Push your changes to a feature branch (e.g. `feature/full-backend-v1`). +3. Open a Pull Request on Gitea targeting `main`. +4. Request review from **devops (Talal)**. 5. Once approved and merged, the staging server rebuilds and redeploys automatically. -### Environment - The `.env` file is **not committed**. It lives only on the staging server at `/opt/encoach/backend-v2/.env`. ---- +## Local Development -# Odoo 19 Community – Local setup (macOS) - -Run Odoo 19 Community on your Mac. - ---- - -## Option A: Run with Docker (easiest) - -No Python or PostgreSQL needed on your machine. - -**Requirements:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) for Mac. +### Option A: Docker (easiest) ```bash -cd /Users/yamenahmad/projects2026/odoo/odoo19 docker compose up -d ``` -Open **http://localhost:8069**. First time: create a new database (name, email, password). - -**Test that it’s running:** -```bash -./test_odoo.sh -``` +Open `http://localhost:8069`. First run: create a new database. Stop: `docker compose down` ---- +### Option B: Source (venv + PostgreSQL) -**Manual terminal guide (no scripts):** see **[MANUAL-RUN.md](MANUAL-RUN.md)** for step-by-step commands only. - ---- - -## Option B: Run from source (venv + PostgreSQL) - -## Prerequisites - -- **macOS** (Sonoma, Ventura, or Monterey) -- **Homebrew** – [brew.sh](https://brew.sh) – install with: - ```bash - /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - ``` -- **Xcode Command Line Tools** (for compilers): - ```bash - xcode-select --install - ``` - -## 1. Install PostgreSQL and wkhtmltopdf +**Prerequisites:** macOS, Homebrew, Python 3.11+, PostgreSQL 15+ ```bash brew install postgresql@15 wkhtmltopdf brew services start postgresql@15 -``` - -Create an Odoo database user (optional; you can also use your macOS user): - -```bash -# Using your current user (no password by default on Mac) createuser -s $(whoami) -# Or create a dedicated user with password: -createuser -s odoo -# Then in psql: ALTER USER odoo WITH PASSWORD 'odoo'; -``` - -## 2. Run the setup script - -From this directory: - -```bash chmod +x setup.sh ./setup.sh -``` - -This will: - -- Clone Odoo 19.0 into `./odoo/` -- Create a Python virtual environment in `./venv/` -- Install Python dependencies from `odoo/requirements.txt` - -## 3. Configure Odoo (optional) - -Copy the example config and edit if needed: - -```bash -cp odoo.conf.example odoo.conf -``` - -- **db_user**: your PostgreSQL user (e.g. your Mac username or `odoo`) -- **db_password**: leave empty if you use trust auth (typical on Mac) -- **addons_path**: defaults to `odoo/addons` (Community only) - -## 4. Run Odoo - -```bash ./run.sh ``` -Or manually: +Open `http://localhost:8069`. -```bash -source venv/bin/activate -cd odoo && ./odoo-bin -c ../odoo.conf -``` +See [MANUAL-RUN.md](MANUAL-RUN.md) for step-by-step commands. -- Open **http://localhost:8069** -- First run: create a new database (name, email, password, language) -- Default admin login after creating DB: email `admin`, password `admin` (if you use the demo setup) +## Related Documents -## Useful options - -- **Custom database name:** `./odoo-bin -c odoo.conf -d mydb` -- **Development mode (auto-reload):** add `--dev=all` to the command -- **Install modules at start:** `-i sale,crm` (comma-separated) - -## Troubleshooting - -- **Port 8069 in use:** change `xmlrpc_port` in `odoo.conf` or run with `--http-port=8070` -- **PostgreSQL connection refused:** ensure it’s running: `brew services start postgresql@15` -- **Python / pip errors:** use Python 3.10, 3.11, or 3.12; create a fresh venv and run `pip install -r odoo/requirements.txt` again \ No newline at end of file +| Document | Description | +|----------|-------------| +| `ENCOACH_ODOO19_BACKEND_SRS.md` | Backend SRS v3.0 (definitive) | +| `ENCOACH_UNIFIED_SRS.md` | Unified frontend + backend SRS v2.0 | +| `ENCOACH_PRODUCT_DESCRIPTION.md` | Non-technical product description | diff --git a/docs/ENCOACH_ODOO19_BACKEND_SRS.md b/docs/ENCOACH_ODOO19_BACKEND_SRS.md new file mode 100644 index 00000000..f93faaad --- /dev/null +++ b/docs/ENCOACH_ODOO19_BACKEND_SRS.md @@ -0,0 +1,1959 @@ +# EnCoach Platform — Odoo 19 Backend SRS + +**Version:** 3.0 +**Date:** March 11, 2026 +**Status:** Implemented — Staging Verified +**Supersedes:** `ODOO_BACKEND_SRS_v3.md`, `ODOO_MIGRATION_SRS_v2.md`, `ODOO_MIGRATION_SRS.md` +**Frontend Reference:** `ENCOACH_UNIFIED_SRS.md` (v2.0) +**Purpose:** Complete backend specification for the EnCoach Adaptive Learning Platform on Odoo 19. All modules, models, and REST API endpoints have been implemented and deployed to staging. + +### Implementation Status + +| Artifact | Location | +|----------|----------| +| **Backend Repository** | `https://git.albousalh.com/devops/encoach_backend_new_v2.git` (branch: `main`) | +| **Frontend Repository** | `https://git.albousalh.com/devops/encoach_frontend_new_v2.git` (branch: `main`) | +| **Staging Backend (Odoo 19)** | `http://5.189.151.117:8069` | +| **Staging Frontend** | `http://5.189.151.117:3000` | +| **Custom EnCoach Modules** | 27 modules in `new_project/custom_addons/` | +| **OpenEduCat Modules** | 14 community modules in `new_project/openeducat_erp-19.0/` | +| **Total API Routes** | ~377 REST endpoints across 4 controller packages | +| **Deployment** | Docker Compose (Odoo 19 + PostgreSQL 16) | + +**Note:** The developer implemented all features in this SRS plus additional OpenEduCat Enterprise features documented in Section 34 (Beyond-SRS Features). + +--- + +## Table of Contents + +1. [Introduction](#1-introduction) +2. [Architecture Overview](#2-architecture-overview) +3. [OpenEduCat Integration Strategy](#3-openeducat-integration-strategy) +4. [Module Inventory](#4-module-inventory) +5. [Authentication and User Management](#5-authentication-and-user-management) +6. [Entity and Permission System](#6-entity-and-permission-system) +7. [LMS Core (OpenEduCat Bridge)](#7-lms-core-openeducat-bridge) +8. [Academic Year, Term, and Department](#8-academic-year-term-and-department) +9. [Admission and Enrollment](#9-admission-and-enrollment) +10. [Subject Registration](#10-subject-registration) +11. [Exam Engine (EnCoach AI)](#11-exam-engine-encoach-ai) +12. [Institutional Exams (OpenEduCat)](#12-institutional-exams-openeducat) +13. [Assignment System](#13-assignment-system) +14. [Course Assignment Submissions (OpenEduCat)](#14-course-assignment-submissions-openeducat) +15. [Classroom and Group Management](#15-classroom-and-group-management) +16. [Subject Taxonomy Engine](#16-subject-taxonomy-engine) +17. [Adaptive Learning Engine](#17-adaptive-learning-engine) +18. [Learning Resources](#18-learning-resources) +19. [AI Services](#19-ai-services) +20. [Training Content](#20-training-content) +21. [Analytics and Statistics](#21-analytics-and-statistics) +22. [Subscription and Payments](#22-subscription-and-payments) +23. [Support Tickets](#23-support-tickets) +24. [File Storage](#24-file-storage) +25. [Approval Workflows (Enhanced)](#25-approval-workflows-enhanced) +26. [Courseware and Content Delivery](#26-courseware-and-content-delivery) +27. [Communication System](#27-communication-system) +28. [Notification Engine](#28-notification-engine) +29. [FAQ System](#29-faq-system) +30. [Plagiarism Detection](#30-plagiarism-detection) +31. [Official Exam Access](#31-official-exam-access) +32. [Non-Functional Requirements](#32-non-functional-requirements) +33. [Implementation Priority](#33-implementation-priority) +34. [Beyond-SRS Features (Implemented)](#34-beyond-srs-features-implemented) + +--- + +## 1. Introduction + +### 1.1 Scope + +This document specifies the complete Odoo 19 backend for the EnCoach Adaptive Learning Platform. The backend serves a React SPA frontend via REST API. All endpoints use JSON request/response with JWT authentication (except explicitly public endpoints). + +### 1.2 Frontend Contract + +The React frontend has 29 API service modules that define the exact endpoints the backend must implement. This SRS documents every endpoint, its expected request/response shape, and the underlying Odoo models. + +### 1.3 Key Principles + +- **OpenEduCat First:** All traditional LMS features (courses, batches, students, faculty, timetable, attendance, exams, assignments, admissions) use OpenEduCat community modules ported to Odoo 19. +- **EnCoach Extensions:** Custom modules extend OpenEduCat models with fields the platform needs (e.g., `description`, `image`, `max_capacity` on `op.course`). +- **REST API Layer:** All data is exposed via REST controllers in `encoach_api` and `encoach_lms_api` modules. The frontend never uses Odoo's web client or XML-RPC. +- **AI Services:** AI functionality (GPT, Whisper, Polly, ELAI, GPTZero, FAISS) is encapsulated in dedicated `encoach_ai_*` modules with API endpoints. + +--- + +## 2. Architecture Overview + +``` +React SPA (Vite + TypeScript) + │ + ▼ REST API (JSON + JWT) +┌─────────────────────────────────┐ +│ Odoo 19 Server │ +│ │ +│ ┌──────────┐ ┌──────────────┐ │ +│ │ encoach_ │ │ OpenEduCat │ │ +│ │ modules │ │ (ported v19)│ │ +│ └──────────┘ └──────────────┘ │ +│ │ │ │ +│ ▼ ▼ │ +│ PostgreSQL 16 │ +└─────────────────────────────────┘ + │ + ▼ External Services + OpenAI API │ AWS Polly │ ELAI │ GPTZero +``` + +### 2.1 Technology Stack + +| Layer | Technology | +|-------|-----------| +| Framework | Odoo 19 Community Edition | +| Language | Python 3.12+ | +| Database | PostgreSQL 16 | +| LMS Foundation | OpenEduCat (ported from v17 to v19) | +| AI/ML | OpenAI GPT-4o, Whisper (local), AWS Polly, Sentence Transformers, FAISS | +| Authentication | JWT (PyJWT) | +| File Storage | Odoo ir.attachment + optional S3 | +| Deployment | Docker, Docker Compose | + +--- + +## 3. OpenEduCat Integration Strategy + +### 3.1 Modules to Port (v17 → v19) + +| Module | Models | Porting Notes | +|--------|--------|---------------| +| `openeducat_core` | `op.course`, `op.batch`, `op.student`, `op.faculty`, `op.subject`, `op.department`, `op.category`, `op.academic.year`, `op.academic.term`, `op.student.course`, `op.subject.registration` | Core dependency for all other modules | +| `openeducat_timetable` | `op.session`, `op.timing` | Depends on `openeducat_core` | +| `openeducat_attendance` | `op.attendance.register`, `op.attendance.sheet`, `op.attendance.line`, `op.attendance.type` | Depends on `openeducat_core`, `openeducat_timetable` | +| `openeducat_classroom` | `op.classroom` | Depends on `openeducat_facility` | +| `openeducat_facility` | `op.facility`, `op.facility.line` | Dependency of classroom | +| `openeducat_exam` | `op.exam.session`, `op.exam`, `op.exam.type`, `op.exam.attendees`, `op.exam.room`, `op.marksheet.register`, `op.marksheet.line`, `op.result.line`, `op.result.template`, `op.grade.configuration` | Depends on `openeducat_core` | +| `openeducat_assignment` | `op.assignment`, `op.assignment.sub.line`, `grading.assignment`, `grading.assignment.type` | Depends on `openeducat_core` | +| `openeducat_admission` | `op.admission`, `op.admission.register` | Depends on `openeducat_core` | + +### 3.2 Model Extensions (via `encoach_lms_api`) + +The `encoach_lms_api` module uses `_inherit` to add fields missing from OpenEduCat but required by the frontend: + +| Model | Added Fields | +|-------|-------------| +| `op.course` | `description` (Text), `image` (Binary), `max_capacity` (Integer), `status` (Selection: draft/active/archived), `department_id` (Many2one to `op.department`) | +| `op.batch` | `max_students` (Integer), `status` (Selection: draft/active/completed) | +| `op.student` | `enrollment_date` (Date), `status` (Selection: active/inactive/graduated/suspended) | +| `op.faculty` | `department_id` (Many2one to `op.department`), `specialization` (Char) | +| `op.subject` | `credits` (Float), `department_id` (Many2one to `op.department`) | + +### 3.3 Serialization + +All OpenEduCat models need `to_api_dict()` methods on the `encoach_lms_api` inheriting models that convert records to JSON-serializable dictionaries with snake_case keys. Many2one fields are serialized as `{field}_id` (integer) and `{field}_name` (string). + +--- + +## 4. Module Inventory + +| # | Module | Type | Description | +|---|--------|------|-------------| +| 1 | `openeducat_core` | OpenEduCat (port v19) | Course, batch, student, faculty, subject, department, academic year/term | +| 2 | `openeducat_timetable` | OpenEduCat (port v19) | Timetable sessions and timings | +| 3 | `openeducat_attendance` | OpenEduCat (port v19) | Attendance sheets, lines, registers | +| 4 | `openeducat_classroom` | OpenEduCat (port v19) | Physical classrooms | +| 5 | `openeducat_facility` | OpenEduCat (port v19) | Facility management | +| 6 | `openeducat_exam` | OpenEduCat (port v19) | Institutional exam sessions, marksheets, grading | +| 7 | `openeducat_assignment` | OpenEduCat (port v19) | Course assignments and submissions | +| 8 | `openeducat_admission` | OpenEduCat (port v19) | Admission registers and applications | +| 9 | `encoach_core` | Custom | `encoach.user` extensions on `res.users`, entities, roles, permissions, codes, invites | +| 10 | `encoach_api` | Custom | REST API controllers for auth, users, entities, permissions, exams, assignments, classrooms, tickets, subscriptions, stats, storage, approvals | +| 11 | `encoach_lms_api` | Custom | REST API bridge for OpenEduCat models (courses, batches, timetable, attendance, grades, academic years, departments, admissions, subject registration, institutional exams, marksheets, course assignments) | +| 12 | `encoach_ai` | Custom | OpenAI service wrapper, token counting, blacklist, system parameter management | +| 13 | `encoach_ai_media` | Custom | TTS (AWS Polly), STT (Whisper), ELAI avatar video generation | +| 14 | `encoach_ai_generation` | Custom | AI exam content generation for all subjects | +| 15 | `encoach_ai_grading` | Custom | AI grading for writing, speaking, math, IT | +| 16 | `encoach_exam` | Custom | `encoach.exam` model for AI-powered exams | +| 17 | `encoach_assignment` | Custom | `encoach.assignment` model (exam-wrapper assignments) | +| 18 | `encoach_evaluation` | Custom | Evaluation job tracking | +| 19 | `encoach_stats` | Custom | Session tracking and statistics | +| 20 | `encoach_training` | Custom | Training tips, walkthroughs, FAISS embeddings | +| 21 | `encoach_classroom` | Custom | `encoach.classroom.group` for virtual classrooms | +| 22 | `encoach_subscription` | Custom | Packages, payments, discounts, Stripe/PayPal/Paymob | +| 23 | `encoach_registration` | Custom | User registration and batch import | +| 24 | `encoach_ticket` | Custom | Support tickets | +| 25 | `encoach_taxonomy` | Custom | Subject, domain, topic, learning objective models | +| 26 | `encoach_resources` | Custom | Learning resource library | +| 27 | `encoach_adaptive` | Custom | Proficiency tracking, learning plans, progress, content cache | +| 28 | `encoach_adaptive_api` | Custom | REST controllers for adaptive learning | +| 29 | `encoach_adaptive_ai` | Custom | AI services for diagnostics, plan generation, coaching, content generation | +| 30 | `encoach_sis` | Custom | UTAS SIS integration (sync, mapping) | +| 31 | `encoach_branding` | Custom | Whitelabeling configuration | +| 32 | `encoach_courseware` | Custom | Course chapters, chapter materials, chapter progress tracking, AI workbench for content generation | +| 33 | `encoach_communication` | Custom | Discussion boards, threaded posts, announcements, direct messaging | +| 34 | `encoach_notification` | Custom | Notification engine, configurable rules, email/in-app delivery, user preferences | +| 35 | `encoach_faq` | Custom | FAQ categories and items, role-filtered, searchable | + +**Original plan: 8 OpenEduCat + 27 custom = 35 modules** + +### 4.2 Additional Modules (Implemented Beyond SRS) + +The developer added 6 more OpenEduCat community modules: + +| # | Module | Type | Description | +|---|--------|------|-------------| +| 36 | `openeducat_fees` | OpenEduCat (port v19) | Fee plans, student fees, fee terms | +| 37 | `openeducat_library` | OpenEduCat (port v19) | Media catalog, movements, library cards | +| 38 | `openeducat_activity` | OpenEduCat (port v19) | Student activities, activity types | +| 39 | `openeducat_parent` | OpenEduCat (port v19) | Parent-student relationships | +| 40 | `openeducat_erp` | OpenEduCat (port v19) | ERP connector meta-module | +| 41 | `theme_web_openeducat` | OpenEduCat (port v19) | Web theme | + +**Deployed total: 14 OpenEduCat + 27 custom = 41 modules** + +--- + +## 5. Authentication and User Management + +### 5.1 Authentication Model + +JWT-based authentication. Tokens are issued on login and validated on every API request. + +### 5.2 User Model + +Extends `res.users` with `encoach.user` mixin: + +| Field | Type | Description | +|-------|------|-------------| +| `user_type` | Selection | `student`, `teacher`, `admin`, `corporate`, `mastercorporate`, `agent`, `developer` | +| `is_verified` | Boolean | Email verification status | +| `entity_ids` | Many2many | Associated entities | +| `phone` | Char | Phone number | +| `birth_date` | Date | Date of birth | +| `gender` | Selection | `m`, `f`, `o` | +| `op_student_id` | Many2one | Link to `op.student` if user_type is student | +| `op_faculty_id` | Many2one | Link to `op.faculty` if user_type is teacher | + +### 5.3 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/login` | Public | Authenticate user, return JWT + user object | +| `POST` | `/api/logout` | JWT | Invalidate token | +| `GET` | `/api/user` | JWT | Get current authenticated user | +| `POST` | `/api/reset/sendVerification` | Public | Send password reset / verification email | +| `GET` | `/api/users/list` | JWT | Paginated user list with filters (`type`, `entity_id`, `page`, `size`) | +| `GET` | `/api/users/{id}` | JWT | Get user by ID | +| `PATCH` | `/api/users/update` | JWT | Update user (id in body) | +| `POST` | `/api/users/create` | JWT | Create user | +| `POST` | `/api/batch_users` | JWT | Batch create users from CSV/JSON | +| `GET` | `/api/users/export` | JWT | Export users as CSV blob | + +### 5.4 Login Response Shape + +```json +{ + "token": "eyJ...", + "user": { + "id": 1, + "name": "John Doe", + "email": "john@example.com", + "user_type": "admin", + "is_verified": true, + "entities": [ + { "id": 1, "name": "UTAS", "logo": "..." } + ] + } +} +``` + +--- + +## 6. Entity and Permission System + +### 6.1 Entity Model (`encoach.entity`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Entity name | +| `code` | Char | Unique code | +| `type` | Selection | `corporate`, `university`, `freelance` | +| `logo` | Binary | Entity logo | +| `active` | Boolean | Active status | +| `user_ids` | Many2many | Members | +| `role_ids` | One2many | Custom roles | + +### 6.2 Role and Permission Models + +**`encoach.role`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Role name | +| `entity_id` | Many2one | Parent entity | +| `permission_ids` | Many2many | Assigned permissions | + +**`encoach.permission`** + +77+ entity-scoped permissions (e.g., `view_students`, `edit_exam`, `view_payment_record`, `manage_entities`). + +### 6.3 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/entities` | JWT | Paginated entities | +| `GET` | `/api/entities/{id}` | JWT | Entity detail | +| `POST` | `/api/entities` | JWT | Create entity | +| `PATCH` | `/api/entities/{id}` | JWT | Update entity | +| `DELETE` | `/api/entities/{id}` | JWT | Delete entity | +| `GET` | `/api/entities/{entityId}/roles` | JWT | Roles for entity | +| `POST` | `/api/entities/{entityId}/roles` | JWT | Create role | +| `PATCH` | `/api/roles/{roleId}/permissions` | JWT | Update role permissions | +| `GET` | `/api/permissions` | JWT | List permissions (filter by `entity_id`) | + +--- + +## 7. LMS Core (OpenEduCat Bridge) + +### 7.1 Course API + +Backed by `op.course` (extended via `_inherit` in `encoach_lms_api`). + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/courses` | JWT | Paginated courses (filter: `status`, `department_id`) | +| `GET` | `/api/courses/{id}` | JWT | Course detail with subjects, batches | +| `POST` | `/api/courses` | JWT | Create course | +| `PATCH` | `/api/courses/{id}` | JWT | Update course | +| `DELETE` | `/api/courses/{id}` | JWT | Delete course | +| `POST` | `/api/courses/ai-generate` | JWT | AI-generate course outline (calls OpenAI) | + +**Course Response Shape:** + +```json +{ + "id": 1, + "name": "IELTS Preparation", + "code": "IELTS-101", + "description": "Comprehensive IELTS preparation course", + "department_id": 1, + "department_name": "English", + "max_capacity": 30, + "status": "active", + "subject_ids": [1, 2, 3], + "subject_names": ["Reading", "Writing", "Listening"], + "batch_count": 2, + "student_count": 45, + "image": "base64..." +} +``` + +### 7.2 Batch API + +Backed by `op.batch` (extended). + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/batches` | JWT | Paginated batches (filter: `course_id`, `status`) | +| `GET` | `/api/batches/{id}` | JWT | Batch detail with student list | +| `POST` | `/api/batches` | JWT | Create batch | +| `PATCH` | `/api/batches/{id}` | JWT | Update batch | +| `DELETE` | `/api/batches/{id}` | JWT | Delete batch | + +### 7.3 Timetable API + +Backed by `op.session` and `op.timing`. + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/timetable` | JWT | Sessions (filter: `course_id`, `batch_id`, `faculty_id`, `start_date`, `end_date`) | +| `POST` | `/api/timetable` | JWT | Create timetable session | + +**Session Response Shape:** + +```json +{ + "id": 1, + "name": "IELTS Reading - Week 1", + "course_id": 1, + "course_name": "IELTS Preparation", + "batch_id": 1, + "batch_name": "Batch A", + "faculty_id": 5, + "faculty_name": "Dr. Smith", + "subject_id": 1, + "subject_name": "Reading", + "classroom_id": 3, + "classroom_name": "Room 101", + "start_datetime": "2026-03-15T09:00:00", + "end_datetime": "2026-03-15T10:30:00", + "day": "Monday" +} +``` + +### 7.4 Attendance API + +Backed by `op.attendance.sheet` and `op.attendance.line`. + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/attendance` | JWT | Attendance records (filter: `course_id`, `batch_id`, `student_id`, `date_from`, `date_to`) | +| `POST` | `/api/attendance` | JWT | Record attendance (batch of student attendance lines) | + +**Attendance Record Request:** + +```json +{ + "session_id": 1, + "attendance_date": "2026-03-15", + "lines": [ + { "student_id": 1, "present": true }, + { "student_id": 2, "present": false, "remark": "Sick leave" } + ] +} +``` + +### 7.5 Grades API + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/grades` | JWT | Grade records (filter: `student_id`, `course_id`, `batch_id`) | + +--- + +## 8. Academic Year, Term, and Department + +### 8.1 Academic Year and Term + +Backed by `op.academic.year` and `op.academic.term` (OpenEduCat core). + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/academic-years` | JWT | List academic years with terms | +| `GET` | `/api/academic-years/{id}` | JWT | Year detail with terms | +| `POST` | `/api/academic-years` | JWT | Create academic year | +| `PATCH` | `/api/academic-years/{id}` | JWT | Update year | +| `DELETE` | `/api/academic-years/{id}` | JWT | Delete year | +| `POST` | `/api/academic-years/{id}/generate-terms` | JWT | Auto-generate terms from `term_structure` | +| `GET` | `/api/academic-terms` | JWT | List terms (filter: `year_id`) | +| `POST` | `/api/academic-terms` | JWT | Create term | +| `PATCH` | `/api/academic-terms/{id}` | JWT | Update term | +| `DELETE` | `/api/academic-terms/{id}` | JWT | Delete term | + +**Generate Terms Logic:** + +Given `term_structure` on the academic year, compute term dates: +- `two_sem`: 2 terms splitting the year in half +- `two_sem_qua`: 2 semesters, each with 2 quarters (4 terms total) +- `three_sem`: 3 trimesters +- `four_Quarter`: 4 quarters +- `final_year`: single term spanning the full year + +### 8.2 Department + +Backed by `op.department` (OpenEduCat core). + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/departments` | JWT | List departments | +| `POST` | `/api/departments` | JWT | Create department | +| `PATCH` | `/api/departments/{id}` | JWT | Update department | +| `DELETE` | `/api/departments/{id}` | JWT | Delete department | + +**Department Response:** + +```json +{ + "id": 1, + "name": "Department of Mathematics", + "code": "MATH", + "parent_id": null, + "parent_name": null, + "course_count": 5, + "faculty_count": 12 +} +``` + +--- + +## 9. Admission and Enrollment + +### 9.1 Admission Register + +Backed by `op.admission.register` (OpenEduCat). + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/admission-registers` | JWT | List registers | +| `POST` | `/api/admission-registers` | JWT | Create register | +| `PATCH` | `/api/admission-registers/{id}` | JWT | Update register | +| `POST` | `/api/admission-registers/{id}/confirm` | JWT | Confirm register (opens enrollment) | +| `POST` | `/api/admission-registers/{id}/close` | JWT | Close register | + +### 9.2 Admission + +Backed by `op.admission` (OpenEduCat). + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/admissions` | JWT | List admissions (filter: `state`, `register_id`, `course_id`, `page`, `size`) | +| `GET` | `/api/admissions/{id}` | JWT | Admission detail | +| `POST` | `/api/admissions` | Public* | Submit admission application | +| `POST` | `/api/admissions/{id}/submit` | JWT | Submit for review | +| `POST` | `/api/admissions/{id}/confirm` | JWT | Confirm admission | +| `POST` | `/api/admissions/{id}/admit` | JWT | Admit applicant | +| `POST` | `/api/admissions/{id}/reject` | JWT | Reject admission | + +*Note: `POST /api/admissions` is public when submitted via the `/apply` page. Backend should allow unauthenticated submission when the register allows public applications. + +### 9.3 Admit Action Logic + +When an admission is admitted (`/admit`): +1. Create `op.student` record from admission data +2. Create `res.users` record with `user_type=student` +3. Create `op.student.course` linking student to course/batch +4. Set `admission.student_id` to the new student +5. Set `admission.state` to `admission` +6. Send welcome email with login credentials + +--- + +## 10. Subject Registration + +### 10.1 Model + +Backed by `op.subject.registration` (OpenEduCat core). + +### 10.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/subject-registrations` | JWT | List registrations (filter: `student_id`, `course_id`, `state`) | +| `POST` | `/api/subject-registrations` | JWT | Create registration | +| `PATCH` | `/api/subject-registrations/{id}` | JWT | Update selected subjects | +| `POST` | `/api/subject-registrations/{id}/confirm` | JWT | Confirm registration | +| `POST` | `/api/subject-registrations/{id}/reject` | JWT | Reject registration | +| `GET` | `/api/subject-registrations/available` | JWT | Get available subjects for current student's enrolled courses | + +### 10.3 Available Subjects Logic + +For the current user (student): +1. Find all `op.student.course` records for this student +2. Get subjects linked to those courses +3. Exclude subjects already registered in confirmed registrations +4. Check unit load limits from `op.course` configuration +5. Return list with `min_unit_load`, `max_unit_load` + +--- + +## 11. Exam Engine (EnCoach AI) + +### 11.1 Model (`encoach.exam`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Exam title | +| `module` | Selection | `reading`, `writing`, `listening`, `speaking`, `math`, `it`, ... | +| `subject_id` | Many2one | Link to `encoach.subject` (taxonomy) | +| `topic_ids` | Many2many | Link to `encoach.topic` | +| `entity_id` | Many2one | Owning entity | +| `structure_id` | Many2one | Exam structure template | +| `rubric_id` | Many2one | Grading rubric | +| `exercises` | Text (JSON) | Generated exercises content | +| `is_public` | Boolean | Public access flag | +| `status` | Selection | `draft`, `published`, `archived` | + +### 11.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/exam/{module}` | JWT | List exams for module (paginated) | +| `GET` | `/api/exam/{module}/{id}` | JWT | Exam detail | +| `POST` | `/api/exam` | JWT | Create exam | +| `PATCH` | `/api/exam/{id}` | JWT | Update exam | +| `DELETE` | `/api/exam/{id}` | JWT | Delete exam | +| `PATCH` | `/api/exam/{id}/access` | JWT | Set public/private | +| `GET` | `/api/rubrics` | JWT | List rubrics (paginated) | +| `POST` | `/api/rubrics` | JWT | Create rubric | +| `GET` | `/api/rubric-groups` | JWT | List rubric groups | +| `GET` | `/api/exam-structures` | JWT | List exam structures | +| `POST` | `/api/exam-structures` | JWT | Create exam structure | +| `DELETE` | `/api/exam-structures/{id}` | JWT | Delete structure | +| `GET` | `/api/exam/avatars` | JWT | List ELAI avatars | +| `POST` | `/api/exam/{module}/generate` | JWT | Generate exercises from existing exam | +| `POST` | `/api/exam/{module}/generate/scratch` | JWT | Generate full exam from scratch | + +### 11.3 Generation Logic + +Uses OpenAI GPT-4o to generate exam content. Prompt templates vary by module: +- **Reading/Listening:** Passage + comprehension questions +- **Writing:** Task description + sample topics +- **Speaking:** Dialogue prompts + follow-up questions +- **Math:** Problem sets with numerical answers, configurable difficulty +- **IT:** Code completion, debugging, conceptual questions + +--- + +## 12. Institutional Exams (OpenEduCat) + +### 12.1 Overview + +Traditional institutional exams (midterms, finals) managed through OpenEduCat. Separate from EnCoach AI exams. + +### 12.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/inst-exam-sessions` | JWT | List exam sessions | +| `POST` | `/api/inst-exam-sessions` | JWT | Create session | +| `GET` | `/api/inst-exam-sessions/{id}` | JWT | Session detail with exams | +| `PATCH` | `/api/inst-exam-sessions/{id}` | JWT | Update session | +| `DELETE` | `/api/inst-exam-sessions/{id}` | JWT | Delete session | +| `POST` | `/api/inst-exam-sessions/{id}/schedule` | JWT | Schedule session | +| `POST` | `/api/inst-exam-sessions/{id}/done` | JWT | Mark session done | +| `POST` | `/api/inst-exams` | JWT | Add exam to session | +| `PATCH` | `/api/inst-exams/{id}` | JWT | Update exam | +| `POST` | `/api/inst-exams/{id}/attendees` | JWT | Add attendees to exam | +| `PATCH` | `/api/inst-exams/{id}/marks` | JWT | Enter marks for attendees | +| `GET` | `/api/exam-types` | JWT | List exam types | +| `POST` | `/api/exam-types` | JWT | Create exam type | +| `GET` | `/api/grade-config` | JWT | List grade configurations | +| `POST` | `/api/grade-config` | JWT | Create grade config | +| `GET` | `/api/result-templates` | JWT | List result templates | +| `POST` | `/api/result-templates` | JWT | Create result template | +| `POST` | `/api/result-templates/{id}/generate` | JWT | Generate marksheets | +| `GET` | `/api/marksheets` | JWT | List marksheets | +| `GET` | `/api/marksheets/{id}` | JWT | Marksheet detail with student results | +| `POST` | `/api/marksheets/{id}/validate` | JWT | Validate marksheet | + +### 12.3 Enter Marks Request + +```json +{ + "attendees": [ + { "student_id": 1, "marks": 85 }, + { "student_id": 2, "marks": 72 } + ] +} +``` + +### 12.4 Generate Marksheets Logic + +1. Create `op.marksheet.register` from `op.result.template` +2. For each student in the batch: + - Create `op.marksheet.line` + - For each exam in the session: create `op.result.line` with marks from `op.exam.attendees` + - Compute total marks, percentage + - If evaluation_type is `grade`: lookup `op.grade.configuration` to assign grade + - Compute pass/fail from `min_marks` on each exam +3. Compute `total_pass` and `total_failed` on register + +--- + +## 13. Assignment System (EnCoach AI) + +### 13.1 Model (`encoach.assignment`) + +Exam-wrapper assignments where an EnCoach exam is assigned to students/classrooms. + +### 13.2 Enhanced Fields (Late Submission + Plagiarism) + +Add to `encoach.assignment`: + +| Field | Type | Description | +|-------|------|-------------| +| `late_deadline` | Datetime | Final late submission cutoff | +| `penalty_type` | Selection | `none`, `percentage`, `fixed_deduction` | +| `penalty_value` | Float | Penalty amount | +| `max_submissions` | Integer | Maximum allowed submissions (0 = unlimited) | +| `allow_extensions` | Boolean | Student extension requests | +| `plagiarism_enabled` | Boolean | Enable GPTZero plagiarism check | +| `plagiarism_max_checks` | Integer | Max plagiarism checks per submission | +| `reminder_count` | Integer | Number of reminders | +| `reminder_frequency` | Selection | `once`, `daily`, `custom` | + +### 13.3 Extension Request Model (`encoach.extension.request`) + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one (`res.users`) | Requesting student | +| `assignment_id` | Many2one | Target assignment | +| `reason` | Text | Justification | +| `requested_date` | Datetime | New deadline | +| `status` | Selection | `pending`, `approved`, `rejected` | +| `approved_by` | Many2one | Approving teacher | +| `response_note` | Text | Teacher response | + +### 13.4 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/assignments` | JWT | Paginated assignments | +| `GET` | `/api/assignments/{id}` | JWT | Assignment detail | +| `POST` | `/api/assignments` | JWT | Create assignment (includes late submission fields) | +| `PATCH` | `/api/assignments/{id}` | JWT | Update assignment | +| `DELETE` | `/api/assignments/{id}` | JWT | Delete assignment | +| `POST` | `/api/assignments/{id}/archive` | JWT | Archive assignment | +| `POST` | `/api/assignments/{id}/start` | JWT | Start assignment (student) | +| `POST` | `/api/assignments/{id}/request-extension` | JWT (student) | Request deadline extension | +| `GET` | `/api/assignments/{id}/extension-requests` | JWT (teacher) | List extension requests | +| `POST` | `/api/extension-requests/{id}/respond` | JWT (teacher) | Approve/reject extension | + +--- + +## 14. Course Assignment Submissions (OpenEduCat) + +### 14.1 Overview + +Traditional file-based assignments where students upload work and teachers grade it. Uses OpenEduCat models. + +### 14.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/course-assignments` | JWT | List course assignments (filter: `course_id`, `batch_id`, `state`) | +| `POST` | `/api/course-assignments` | JWT | Create course assignment | +| `GET` | `/api/course-assignments/{id}` | JWT | Assignment detail with submissions | +| `PATCH` | `/api/course-assignments/{id}` | JWT | Update assignment | +| `POST` | `/api/course-assignments/{id}/publish` | JWT | Publish assignment | +| `POST` | `/api/course-assignments/{id}/finish` | JWT | Close assignment | +| `GET` | `/api/course-assignments/{id}/submissions` | JWT | List student submissions | +| `POST` | `/api/course-assignments/{id}/submit` | JWT | Student file upload (multipart/form-data) | +| `PATCH` | `/api/submissions/{id}` | JWT | Grade submission (marks, feedback, status) | +| `GET` | `/api/assignment-types` | JWT | List assignment types | +| `POST` | `/api/assignment-types` | JWT | Create assignment type | + +### 14.3 File Upload + +Student submission accepts `multipart/form-data`: +- `file`: Binary file attachment +- `description`: Optional text description + +Files are stored as `ir.attachment` records linked to `op.assignment.sub.line`. + +### 14.4 Grading Request + +```json +{ + "marks": 85, + "state": "accept", + "note": "Well researched paper. Minor formatting issues." +} +``` + +--- + +## 15. Classroom and Group Management + +### 15.1 Model (`encoach.classroom.group`) + +Virtual classrooms for grouping students within entities. + +### 15.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/groups` | JWT | Paginated groups | +| `GET` | `/api/groups/{id}` | JWT | Group detail with members | +| `POST` | `/api/groups` | JWT | Create group | +| `DELETE` | `/api/groups/{id}` | JWT | Delete group | +| `POST` | `/api/groups/transfer` | JWT | Transfer students between groups | +| `POST` | `/api/groups/{id}/members` | JWT | Add members | +| `POST` | `/api/groups/{id}/members/remove` | JWT | Remove members | + +--- + +## 16. Subject Taxonomy Engine + +### 16.1 Models + +**`encoach.subject`** (distinct from `op.subject`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Subject name (e.g., "IELTS", "Mathematics", "Information Technology") | +| `code` | Char | Unique code | +| `description` | Text | Description | +| `icon` | Char | Icon identifier | +| `active` | Boolean | Active flag | +| `domain_ids` | One2many | Child domains | + +**`encoach.domain`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Domain name (e.g., "Algebra", "Networking") | +| `subject_id` | Many2one | Parent subject | +| `topic_ids` | One2many | Child topics | + +**`encoach.topic`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Topic name | +| `domain_id` | Many2one | Parent domain | +| `subject_id` | Many2one (related) | Subject via domain | +| `difficulty` | Selection | `beginner`, `intermediate`, `advanced` | +| `prerequisite_ids` | Many2many | Prerequisite topics | +| `learning_objective_ids` | One2many | Learning objectives | + +**`encoach.learning.objective`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Objective description | +| `topic_id` | Many2one | Parent topic | +| `bloom_level` | Selection | `remember`, `understand`, `apply`, `analyze`, `evaluate`, `create` | + +### 16.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/subjects` | JWT | List subjects | +| `GET` | `/api/subjects/{id}` | JWT | Subject detail | +| `POST` | `/api/subjects` | JWT | Create subject | +| `PATCH` | `/api/subjects/{id}` | JWT | Update subject | +| `DELETE` | `/api/subjects/{id}` | JWT | Delete subject | +| `GET` | `/api/subjects/{subjectId}/taxonomy` | JWT | Full taxonomy tree (domains → topics → objectives) | +| `POST` | `/api/subjects/{subjectId}/taxonomy/import` | JWT | Import taxonomy from file (multipart) | +| `GET` | `/api/domains` | JWT | List domains (filter: `subject_id`) | +| `POST` | `/api/domains` | JWT | Create domain | +| `PATCH` | `/api/domains/{id}` | JWT | Update domain | +| `DELETE` | `/api/domains/{id}` | JWT | Delete domain | +| `POST` | `/api/domains/{domainId}/ai-suggest` | JWT | AI-suggest topics for domain | +| `GET` | `/api/topics` | JWT | List topics (filter: `domain_id`, `subject_id`) | +| `POST` | `/api/topics` | JWT | Create topic | +| `PATCH` | `/api/topics/{id}` | JWT | Update topic | +| `DELETE` | `/api/topics/{id}` | JWT | Delete topic | + +--- + +## 17. Adaptive Learning Engine + +### 17.1 Models + +**`encoach.proficiency`** + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Student user | +| `subject_id` | Many2one | Subject | +| `topic_id` | Many2one | Topic | +| `mastery_score` | Float | 0.0 to 1.0 | +| `confidence` | Float | Statistical confidence | +| `last_assessed` | Datetime | Last assessment time | +| `assessment_count` | Integer | Number of assessments | + +**`encoach.learning.plan`** + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Student | +| `subject_id` | Many2one | Subject | +| `status` | Selection | `active`, `paused`, `completed` | +| `items` | One2many | Plan items (topics in order) | +| `generated_by` | Selection | `ai`, `manual` | +| `progress` | Float | Computed completion percentage | + +**`encoach.learning.plan.item`** + +| Field | Type | Description | +|-------|------|-------------| +| `plan_id` | Many2one | Parent plan | +| `topic_id` | Many2one | Topic | +| `sequence` | Integer | Order in plan | +| `status` | Selection | `locked`, `available`, `in_progress`, `completed` | +| `estimated_hours` | Float | Estimated time | +| `mastery_threshold` | Float | Required mastery to complete | + +**`encoach.diagnostic.session`** + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Student | +| `subject_id` | Many2one | Subject | +| `status` | Selection | `in_progress`, `completed` | +| `questions_answered` | Integer | Count | +| `result_data` | Text (JSON) | Topic-level results | + +**`encoach.content.cache`** + +| Field | Type | Description | +|-------|------|-------------| +| `topic_id` | Many2one | Topic | +| `content_type` | Selection | `explanation`, `practice`, `quiz` | +| `content` | Text (JSON) | Cached AI content | +| `generated_at` | Datetime | Generation time | +| `ttl_hours` | Integer | Cache TTL | + +### 17.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/diagnostic/start` | JWT | Start diagnostic for subject | +| `POST` | `/api/diagnostic/answer` | JWT | Submit diagnostic answer (adaptive next question) | +| `GET` | `/api/diagnostic/{sessionId}/result` | JWT | Get diagnostic result | +| `GET` | `/api/proficiency` | JWT | Get proficiency records (filter: `subject_id`, `student_id`) | +| `GET` | `/api/proficiency/summary` | JWT | Aggregate proficiency summary | +| `GET` | `/api/proficiency/class` | JWT | Class-wide proficiency | +| `GET` | `/api/learning-plan` | JWT | Get learning plan (filter: `subject_id`) | +| `POST` | `/api/learning-plan/generate` | JWT | AI-generate learning plan | +| `PATCH` | `/api/learning-plan/{id}` | JWT | Update plan | +| `POST` | `/api/learning-plan/{id}/pause` | JWT | Pause plan | +| `POST` | `/api/learning-plan/{id}/resume` | JWT | Resume plan | +| `GET` | `/api/topics/{topicId}/content` | JWT | Get topic learning content | +| `POST` | `/api/topics/{topicId}/generate-content` | JWT | AI-generate topic content | +| `POST` | `/api/topics/{topicId}/practice` | JWT | Generate practice questions | +| `POST` | `/api/topics/{topicId}/practice/grade` | JWT | Grade practice answers | +| `POST` | `/api/topics/{topicId}/mastery-quiz` | JWT | Start mastery quiz | +| `POST` | `/api/topics/{topicId}/mastery-quiz/submit` | JWT | Submit mastery quiz and update proficiency | + +### 17.3 Diagnostic Algorithm + +Computer Adaptive Testing (CAT): +1. Start with medium-difficulty questions +2. If correct → harder question; if incorrect → easier question +3. Uses Item Response Theory (IRT) to estimate ability +4. Covers multiple topics within the subject +5. Terminates after sufficient confidence or max questions (20-30) +6. Produces per-topic mastery scores + +### 17.4 Learning Plan Generation + +AI-generated study plan: +1. Read student's proficiency profile +2. Identify weak topics (mastery < threshold) +3. Respect prerequisite graph (topological sort) +4. Estimate time per topic based on gap +5. Order topics: prerequisites first, then weakest areas +6. Return ordered list of `plan_items` + +--- + +## 18. Learning Resources + +### 18.1 Model (`encoach.resource`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Resource title | +| `type` | Selection | `video`, `document`, `link`, `interactive` | +| `subject_id` | Many2one | Subject | +| `topic_ids` | Many2many | Topics | +| `file` | Binary | Uploaded file | +| `url` | Char | External URL | +| `difficulty` | Selection | `beginner`, `intermediate`, `advanced` | +| `duration_minutes` | Integer | Estimated duration | +| `active` | Boolean | Soft-delete flag | + +### 18.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/resources` | JWT | Paginated resources (filter: `subject_id`, `topic_id`, `type`, `difficulty`) | +| `POST` | `/api/resources` | JWT | Upload resource (multipart) | +| `PATCH` | `/api/resources/{id}` | JWT | Update resource metadata | +| `DELETE` | `/api/resources/{id}` | JWT | Soft-delete resource | +| `POST` | `/api/resources/{id}/complete` | JWT | Mark resource as completed by student | +| `POST` | `/api/resources/{id}/rate` | JWT | Rate resource (1-5) | +| `GET` | `/api/resources/{id}/download` | JWT | Download resource file | + +--- + +## 19. AI Services + +### 19.1 AI Coaching + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/coach/chat` | JWT | General AI chat (context-aware) | +| `POST` | `/api/coach/hint` | JWT | Hint for topic/question | +| `POST` | `/api/coach/explain` | JWT | Explain scores or concepts | +| `POST` | `/api/coach/suggest` | JWT | Study suggestions | +| `POST` | `/api/coach/writing-help` | JWT | Writing feedback with improved text | +| `GET` | `/api/coach/tip` | JWT | Context-aware tip (FAISS similarity) | + +### 19.2 AI Evaluation + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/evaluate/writing` | JWT | Evaluate writing (IELTS band scoring / rubric-based) | +| `POST` | `/api/evaluate/speaking` | JWT | Evaluate speaking (audio → transcribe → grade) | +| `POST` | `/api/grading/multiple` | JWT | Grade multiple-choice / numerical answers | +| `POST` | `/api/transcribe` | JWT | Audio transcription (Whisper, multipart upload) | + +### 19.3 AI Generation + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/exam/{module}/generate` | JWT | Generate exam exercises from template | +| `POST` | `/api/exam/{module}/generate/scratch` | JWT | Generate full exam from scratch | + +### 19.4 Media Generation + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/exam/listening/media` | JWT | Generate listening audio (AWS Polly TTS) | +| `POST` | `/api/exam/speaking/media` | JWT | Generate speaking video (ELAI) | +| `GET` | `/api/exam/avatars` | JWT | List ELAI avatars with voice metadata | + +### 19.5 AI Analytics + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/ai/search` | JWT | AI-powered semantic search | +| `POST` | `/api/ai/insights` | JWT | AI-generated insights from data | +| `GET` | `/api/ai/alerts` | JWT | AI-detected alerts (at-risk students, anomalies) | +| `POST` | `/api/ai/report-narrative` | JWT | AI narrative for reports | +| `POST` | `/api/ai/batch-optimize` | JWT | Batch optimization suggestions | +| `POST` | `/api/ai/grade-suggest` | JWT | AI grading suggestion | + +### 19.6 AI Service Configuration + +All AI services read configuration from `ir.config_parameter`: + +| Parameter Key | Description | Default | +|--------------|-------------|---------| +| `encoach.openai_api_key` | OpenAI API key | Required | +| `encoach.openai_model` | Default model | `gpt-4o` | +| `encoach.openai_model_light` | Light model for simple tasks | `gpt-3.5-turbo` | +| `encoach.aws_access_key_id` | AWS access key | Required | +| `encoach.aws_secret_access_key` | AWS secret key | Required | +| `encoach.aws_region` | AWS region | `eu-west-1` | +| `encoach.polly_voice_id` | Default Polly voice | `Joanna` | +| `encoach.polly_engine` | Polly engine | `neural` | +| `encoach.whisper_model` | Whisper model size | `base` | +| `encoach.whisper_workers` | Whisper worker threads | `4` | +| `encoach.elai_api_key` | ELAI API key | Required | +| `encoach.gptzero_api_key` | GPTZero API key | Required | +| `encoach.faiss_embedding_model` | Sentence transformer model | `all-MiniLM-L6-v2` | + +--- + +## 20. Training Content + +### 20.1 Models + +**`encoach.training.tip`** + +| Field | Type | Description | +|-------|------|-------------| +| `title` | Char | Tip title | +| `content` | Text | Tip content | +| `subject_id` | Many2one | Subject | +| `module` | Char | Module tag | +| `embedding` | Binary(attachment=False) | FAISS embedding vector | + +**`encoach.training.walkthrough`** + +| Field | Type | Description | +|-------|------|-------------| +| `title` | Char | Walkthrough title | +| `steps` | Text (JSON) | Step-by-step content | +| `module` | Char | Module tag | + +### 20.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/training` | JWT | Training records (filter: `entity_id`, `user_id`, `module`) | +| `GET` | `/api/training/tips` | JWT | Training tips | +| `GET` | `/api/training/walkthrough` | JWT | Walkthroughs (filter: `module`) | + +--- + +## 21. Analytics and Statistics + +### 21.1 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/sessions` | JWT | Exam sessions | +| `GET` | `/api/stats` | JWT | Exam statistics | +| `GET` | `/api/statistical` | JWT | Aggregated statistical data | +| `GET` | `/api/stats/performance` | JWT | Performance metrics | +| `GET` | `/api/analytics/student` | JWT | Student analytics (filter: `student_id`, `subject_id`, `date_range`) | +| `GET` | `/api/analytics/class` | JWT | Class analytics (filter: `batch_id`, `course_id`) | +| `GET` | `/api/analytics/subject` | JWT | Subject analytics (filter: `subject_id`) | +| `GET` | `/api/analytics/content-gaps` | JWT | Content gap analysis | + +--- + +## 22. Subscription and Payments + +### 22.1 Models + +**`encoach.package`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Package name | +| `description` | Text | Description | +| `price` | Float | Price | +| `currency` | Char | Currency code | +| `duration_days` | Integer | Access duration | +| `subject_ids` | Many2many | Included subjects | +| `features` | Text (JSON) | Feature list | +| `active` | Boolean | Available for purchase | + +**`encoach.payment`** + +| Field | Type | Description | +|-------|------|-------------| +| `user_id` | Many2one | Paying user | +| `entity_id` | Many2one | Entity (if institutional) | +| `package_id` | Many2one | Package | +| `amount` | Float | Payment amount | +| `currency` | Char | Currency | +| `provider` | Selection | `stripe`, `paypal`, `paymob`, `invoice` | +| `status` | Selection | `pending`, `completed`, `failed`, `refunded` | +| `provider_ref` | Char | External reference | +| `created_at` | Datetime | Payment date | + +**`encoach.discount`** + +| Field | Type | Description | +|-------|------|-------------| +| `code` | Char | Discount code | +| `percentage` | Float | Discount percentage | +| `valid_from` | Datetime | Start date | +| `valid_to` | Datetime | End date | +| `max_uses` | Integer | Maximum uses | +| `current_uses` | Integer | Current use count | + +### 22.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/packages` | JWT | List packages | +| `GET` | `/api/payments` | JWT | Paginated payments | +| `POST` | `/api/stripe/checkout` | JWT | Create Stripe checkout session, return URL | +| `POST` | `/api/paypal/checkout` | JWT | Create PayPal order, return approval URL | +| `POST` | `/api/paymob/checkout` | JWT | Create Paymob payment, return URL | +| `GET` | `/api/discounts` | JWT | List discounts | +| `POST` | `/api/discounts` | JWT | Create discount | +| `DELETE` | `/api/discounts/{id}` | JWT | Delete discount | + +### 22.3 Webhook Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/stripe/webhook` | Webhook signature | Stripe payment events | +| `POST` | `/api/paypal/webhook` | Webhook signature | PayPal payment events | +| `POST` | `/api/paymob/webhook` | Webhook HMAC | Paymob transaction callback | + +--- + +## 23. Support Tickets + +### 23.1 Model (`encoach.ticket`) + +| Field | Type | Description | +|-------|------|-------------| +| `subject` | Char | Ticket subject | +| `description` | Text | Description | +| `type` | Selection | `bug`, `feature`, `support`, `feedback` | +| `status` | Selection | `open`, `in_progress`, `resolved`, `closed` | +| `reporter_id` | Many2one | Reporter user | +| `assignee_id` | Many2one | Assigned staff | +| `entity_id` | Many2one | Entity context | +| `source` | Selection | `platform`, `webpage` | + +### 23.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/tickets` | JWT | Paginated tickets (filter: `status`, `type`, `assignee_id`, `source`) | +| `POST` | `/api/tickets` | JWT | Create ticket | +| `PATCH` | `/api/tickets/{id}` | JWT | Update ticket | +| `GET` | `/api/tickets/assignedToUser` | JWT | Tickets assigned to current user | + +--- + +## 24. File Storage + +### 24.1 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/storage/upload` | JWT | Upload file (multipart/form-data), return attachment ID and URL | +| `GET` | `/api/storage/url` | JWT | Resolve download URL for filename | + +Files are stored as `ir.attachment` records. For production, configure Odoo to use S3-compatible storage. + +--- + +## 25. Approval Workflows (Enhanced) + +### 25.1 Model (`encoach.approval.workflow`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Workflow name | +| `type` | Selection | `exam_publish`, `assignment_publish`, `content_publish`, `material_publish` | +| `stage_ids` | One2many | Approval stages (ordered) | +| `entity_id` | Many2one | Entity | +| `allow_bypass` | Boolean | Whether bypass is allowed | +| `active` | Boolean | Active flag | + +### 25.2 Model (`encoach.approval.stage`) + +| Field | Type | Description | +|-------|------|-------------| +| `workflow_id` | Many2one | Parent workflow | +| `sequence` | Integer | Stage order | +| `approver_id` | Many2one | Assigned approver (`res.users`) | +| `max_days` | Integer | Maximum days before auto-escalation | +| `auto_escalate` | Boolean | Whether to auto-escalate on timeout | +| `notification_email` | Char | Email for stage notifications | +| `status` | Selection | `pending`, `approved`, `rejected`, `escalated`, `bypassed` | +| `comment` | Text | Reviewer comment | +| `acted_at` | Datetime | When action was taken | + +### 25.3 Model (`encoach.approval.request`) + +| Field | Type | Description | +|-------|------|-------------| +| `workflow_id` | Many2one | Workflow template | +| `res_model` | Char | Target model (e.g., `encoach.exam`) | +| `res_id` | Integer | Target record ID | +| `current_stage_id` | Many2one | Current active stage | +| `requester_id` | Many2one | User who submitted for approval | +| `state` | Selection | `in_progress`, `approved`, `rejected`, `bypassed` | +| `bypass_reason` | Text | Justification if bypassed | +| `created_at` | Datetime | Request creation time | + +### 25.4 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/approval-workflows` | JWT | Paginated workflows | +| `POST` | `/api/approval-workflows` | JWT | Create workflow with stages | +| `GET` | `/api/approval-workflows/{id}` | JWT | Get workflow with stages | +| `PATCH` | `/api/approval-workflows/{id}` | JWT | Update workflow and stages | +| `DELETE` | `/api/approval-workflows/{id}` | JWT | Delete workflow | +| `POST` | `/api/approval-requests` | JWT | Submit item for approval | +| `GET` | `/api/approval-requests` | JWT | List approval requests (filter: state, type) | +| `POST` | `/api/approval-requests/{id}/approve` | JWT | Approve current stage | +| `POST` | `/api/approval-requests/{id}/reject` | JWT | Reject at current stage | +| `POST` | `/api/approval-requests/{id}/bypass` | JWT | Bypass approval (requires justification) | +| `POST` | `/api/approval-requests/{id}/return` | JWT | Return to specific stage | + +### 25.5 Cron: Auto-Escalation + +A server cron runs daily to check approval stages that have exceeded `max_days`. For stages with `auto_escalate = True`, the system automatically advances to the next stage and sends a notification email to the new approver with escalation reason. + +--- + +## 26. Courseware and Content Delivery + +**Module:** `encoach_courseware` +**Dependencies:** `encoach_core`, `openeducat_core`, `encoach_ai` + +### 26.1 Model (`encoach.course.chapter`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char (required) | Chapter title | +| `course_id` | Many2one (`op.course`) | Parent course | +| `sequence` | Integer | Display order | +| `description` | Text | Chapter description | +| `start_date` | Datetime | Scheduled start date | +| `end_date` | Datetime | Optional end date | +| `unlock_mode` | Selection | `auto_date`, `manual`, `prerequisite` | +| `is_unlocked` | Boolean | Current unlock status | +| `topic_id` | Many2one (`encoach.topic`) | Bridge to adaptive engine | +| `material_ids` | One2many | Chapter materials | +| `assignment_ids` | Many2many (`encoach.assignment`) | Linked assignments | +| `exam_ids` | Many2many (`encoach.exam`) | Linked exams/quizzes | +| `active` | Boolean | Soft-delete flag | + +### 26.2 Model (`encoach.chapter.material`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char (required) | Material title | +| `chapter_id` | Many2one | Parent chapter | +| `type` | Selection | `pdf`, `document`, `video`, `audio`, `image`, `link`, `article` | +| `file` | Binary (attachment=True) | Uploaded file | +| `url` | Char | External URL | +| `description` | Text | Description | +| `sequence` | Integer | Display order | +| `allow_download` | Boolean | Student download permission | +| `is_book` | Boolean | Course book flag | +| `book_chapters` | Text | JSON book chapter structure | +| `active` | Boolean | Soft-delete flag | + +### 26.3 Model (`encoach.chapter.progress`) + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one (`res.users`) | Student | +| `chapter_id` | Many2one | Chapter | +| `status` | Selection | `not_started`, `in_progress`, `completed` | +| `started_at` | Datetime | First access time | +| `completed_at` | Datetime | Completion time | +| `materials_completed` | Integer | Count of materials viewed | +| `materials_total` | Integer | Computed total materials | + +### 26.4 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/courses/{courseId}/chapters` | JWT | List chapters (ordered by sequence) | +| `POST` | `/api/courses/{courseId}/chapters` | JWT (teacher) | Create chapter | +| `GET` | `/api/chapters/{id}` | JWT | Chapter detail with material count | +| `PATCH` | `/api/chapters/{id}` | JWT (teacher) | Update chapter | +| `DELETE` | `/api/chapters/{id}` | JWT (teacher) | Soft-delete chapter | +| `POST` | `/api/chapters/{id}/unlock` | JWT (teacher) | Manually unlock | +| `POST` | `/api/chapters/{id}/lock` | JWT (teacher) | Manually lock | +| `PATCH` | `/api/courses/{courseId}/chapters/reorder` | JWT (teacher) | Reorder (body: `{ids: []}`) | +| `GET` | `/api/chapters/{id}/progress` | JWT | Student progress | +| `POST` | `/api/chapters/{id}/progress/complete` | JWT (student) | Mark chapter completed | +| `GET` | `/api/chapters/{chapterId}/materials` | JWT | List materials | +| `POST` | `/api/chapters/{chapterId}/materials` | JWT (teacher) | Upload material (multipart) | +| `PATCH` | `/api/materials/{id}` | JWT (teacher) | Update material metadata | +| `DELETE` | `/api/materials/{id}` | JWT (teacher) | Delete material | +| `GET` | `/api/materials/{id}/download` | JWT | Download file (streaming response) | +| `POST` | `/api/materials/{id}/viewed` | JWT (student) | Record material view | +| `PATCH` | `/api/chapters/{chapterId}/materials/reorder` | JWT (teacher) | Reorder materials | + +### 26.5 AI Workbench Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/workbench/generate-outline` | JWT (teacher) | AI generates course outline from requirements (topic, objectives, complexity) | +| `POST` | `/api/workbench/generate-chapter` | JWT (teacher) | AI generates content for a specific chapter | +| `POST` | `/api/workbench/generate-rubric` | JWT (teacher) | AI generates grading rubric | +| `POST` | `/api/workbench/regenerate` | JWT (teacher) | Regenerate specific section | +| `POST` | `/api/workbench/suggest-materials` | JWT (teacher) | AI suggests supplementary materials based on student performance profiles | +| `POST` | `/api/workbench/publish` | JWT (teacher) | Publish generated content to course chapters (may trigger approval workflow) | + +AI Workbench uses GPT-4o (temp 0.7 for generation) and calls `encoach_ai` service layer. + +### 26.6 Cron: Auto-Unlock Chapters + +Server cron runs every hour. For chapters with `unlock_mode = 'auto_date'` and `start_date <= now()` and `is_unlocked = False`, set `is_unlocked = True` and trigger notification. + +--- + +## 27. Communication System + +**Module:** `encoach_communication` +**Dependencies:** `encoach_core`, `openeducat_core` + +### 27.1 Model (`encoach.discussion.board`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char (required) | Board title | +| `course_id` | Many2one (`op.course`) | Associated course | +| `batch_id` | Many2one (`op.batch`) | Associated batch (optional) | +| `chapter_id` | Many2one (`encoach.course.chapter`) | Associated chapter (optional) | +| `assignment_id` | Many2one | Associated assignment (optional) | +| `is_enabled` | Boolean | Teacher toggle | +| `allow_student_posts` | Boolean | Student thread creation permission | +| `post_count` | Integer | Computed count of posts | + +### 27.2 Model (`encoach.discussion.post`) + +| Field | Type | Description | +|-------|------|-------------| +| `board_id` | Many2one | Parent board | +| `parent_id` | Many2one (self) | Parent post for threading | +| `author_id` | Many2one (`res.users`) | Author | +| `title` | Char | Thread title (root posts only) | +| `content` | Text | Post body (markdown) | +| `attachment_ids` | Many2many (`ir.attachment`) | File attachments | +| `is_pinned` | Boolean | Teacher pin | +| `is_resolved` | Boolean | Resolved flag (Q&A mode) | +| `reply_count` | Integer | Computed child count | +| `created_at` | Datetime | Post timestamp | + +### 27.3 Model (`encoach.announcement`) + +| Field | Type | Description | +|-------|------|-------------| +| `title` | Char (required) | Announcement title | +| `content` | Text | Body (markdown) | +| `author_id` | Many2one (`res.users`) | Author | +| `course_id` | Many2one (`op.course`) | Target course (null = system-wide) | +| `batch_id` | Many2one (`op.batch`) | Target batch (null = all batches) | +| `priority` | Selection | `normal`, `important`, `urgent` | +| `is_published` | Boolean | Published status | +| `published_at` | Datetime | Publish timestamp | +| `expires_at` | Datetime | Expiry time | +| `send_email` | Boolean | Also send via email | +| `attachment_ids` | Many2many (`ir.attachment`) | Attachments | + +### 27.4 Model (`encoach.message`) + +| Field | Type | Description | +|-------|------|-------------| +| `sender_id` | Many2one (`res.users`) | Sender | +| `recipient_id` | Many2one (`res.users`) | Recipient | +| `subject` | Char | Subject line | +| `content` | Text | Message body | +| `is_read` | Boolean | Read flag | +| `read_at` | Datetime | Read timestamp | +| `attachment_ids` | Many2many (`ir.attachment`) | Attachments | +| `send_email_copy` | Boolean | Send email copy | +| `created_at` | Datetime | Sent time | + +### 27.5 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/discussion-boards` | JWT | List boards (filter: `course_id`, `batch_id`) | +| `POST` | `/api/discussion-boards` | JWT (teacher) | Create board | +| `PATCH` | `/api/discussion-boards/{id}` | JWT (teacher) | Update settings | +| `GET` | `/api/discussion-boards/{id}/posts` | JWT | Paginated posts (threaded) | +| `POST` | `/api/discussion-boards/{id}/posts` | JWT | Create post/reply | +| `PATCH` | `/api/posts/{id}` | JWT | Update own post | +| `DELETE` | `/api/posts/{id}` | JWT (teacher/admin) | Delete post | +| `POST` | `/api/posts/{id}/pin` | JWT (teacher) | Pin/unpin toggle | +| `POST` | `/api/posts/{id}/resolve` | JWT (teacher) | Mark as resolved | +| `GET` | `/api/announcements` | JWT | List announcements (filter: `course_id`, `priority`) | +| `POST` | `/api/announcements` | JWT (teacher/admin) | Create announcement | +| `PATCH` | `/api/announcements/{id}` | JWT | Update | +| `DELETE` | `/api/announcements/{id}` | JWT | Delete | +| `POST` | `/api/announcements/{id}/publish` | JWT | Publish | +| `GET` | `/api/messages` | JWT | Inbox (filter: `is_read`) | +| `GET` | `/api/messages/sent` | JWT | Sent messages | +| `POST` | `/api/messages` | JWT | Send message | +| `GET` | `/api/messages/{id}` | JWT | Message detail (auto-marks read) | +| `DELETE` | `/api/messages/{id}` | JWT | Delete message | +| `GET` | `/api/messages/unread-count` | JWT | Unread count `{count: N}` | + +### 27.6 Email Integration + +When `send_email = True` on announcements or `send_email_copy = True` on messages, the module uses Odoo's `mail.thread` mixin to send emails through the configured outgoing mail server. + +--- + +## 28. Notification Engine + +**Module:** `encoach_notification` +**Dependencies:** `encoach_core` + +### 28.1 Model (`encoach.notification`) + +| Field | Type | Description | +|-------|------|-------------| +| `user_id` | Many2one (`res.users`) | Recipient | +| `title` | Char | Notification title | +| `message` | Text | Body | +| `type` | Selection | `deadline`, `chapter_unlock`, `result_release`, `announcement`, `assignment`, `exam`, `message`, `system` | +| `action_url` | Char | Frontend URL to navigate to | +| `is_read` | Boolean | Read status | +| `read_at` | Datetime | Read timestamp | +| `channel` | Selection | `in_app`, `email`, `both` | +| `created_at` | Datetime | Created time | + +### 28.2 Model (`encoach.notification.rule`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Rule name | +| `event_type` | Selection | `assignment_due`, `exam_due`, `chapter_unlock`, `result_release`, `submission_graded`, `extension_response` | +| `days_before` | Integer | Days before event to trigger | +| `frequency` | Selection | `once`, `daily`, `custom` | +| `custom_intervals` | Text (JSON) | Custom intervals array (e.g., `[7, 3, 1]`) | +| `channel` | Selection | `in_app`, `email`, `both` | +| `entity_id` | Many2one | Entity scope | +| `active` | Boolean | Active flag | + +### 28.3 Model (`encoach.notification.preferences`) + +| Field | Type | Description | +|-------|------|-------------| +| `user_id` | Many2one (`res.users`) | One per user | +| `email_enabled` | Boolean | Master email toggle | +| `assignment_alerts` | Boolean | Assignment notifications | +| `exam_alerts` | Boolean | Exam notifications | +| `chapter_alerts` | Boolean | Chapter unlock notifications | +| `announcement_alerts` | Boolean | Announcement notifications | +| `message_alerts` | Boolean | Message notifications | + +### 28.4 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/notifications` | JWT | Paginated list (filter: `type`, `is_read`) | +| `POST` | `/api/notifications/{id}/read` | JWT | Mark as read | +| `POST` | `/api/notifications/read-all` | JWT | Mark all as read | +| `GET` | `/api/notifications/unread-count` | JWT | `{count: N}` | +| `GET` | `/api/notification-rules` | JWT (admin) | List rules | +| `POST` | `/api/notification-rules` | JWT (admin) | Create rule | +| `PATCH` | `/api/notification-rules/{id}` | JWT (admin) | Update rule | +| `DELETE` | `/api/notification-rules/{id}` | JWT (admin) | Delete rule | +| `GET` | `/api/notification-preferences` | JWT | Get user preferences | +| `PATCH` | `/api/notification-preferences` | JWT | Update preferences | + +### 28.5 Crons + +1. **Deadline Reminders:** Runs daily. Checks all active rules, matches upcoming events (assignments, exams) within `days_before`, creates notifications and sends emails per user preferences. +2. **Chapter Unlock Notifications:** Triggered by the courseware cron when chapters are auto-unlocked. + +--- + +## 29. FAQ System + +**Module:** `encoach_faq` +**Dependencies:** `encoach_core` + +### 29.1 Model (`encoach.faq.category`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Category name | +| `sequence` | Integer | Display order | +| `icon` | Char | Icon identifier | +| `audience` | Selection | `student`, `entity`, `both` | +| `active` | Boolean | Active flag | + +### 29.2 Model (`encoach.faq.item`) + +| Field | Type | Description | +|-------|------|-------------| +| `question` | Char | Question text | +| `answer` | Text | Answer (markdown, embedded images/video) | +| `category_id` | Many2one | Parent category | +| `audience` | Selection | `student`, `entity`, `both` | +| `image` | Binary | Optional image | +| `video_url` | Char | Optional video URL | +| `sequence` | Integer | Display order | +| `active` | Boolean | Active flag | + +### 29.3 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `GET` | `/api/faq/categories` | Public/JWT | List categories (filter: `audience`) | +| `POST` | `/api/faq/categories` | JWT (admin) | Create category | +| `PATCH` | `/api/faq/categories/{id}` | JWT (admin) | Update category | +| `DELETE` | `/api/faq/categories/{id}` | JWT (admin) | Delete category | +| `GET` | `/api/faq/items` | Public/JWT | List items (filter: `category_id`, `audience`, `search`) | +| `POST` | `/api/faq/items` | JWT (admin) | Create item | +| `PATCH` | `/api/faq/items/{id}` | JWT (admin) | Update item | +| `DELETE` | `/api/faq/items/{id}` | JWT (admin) | Delete item | + +--- + +## 30. Plagiarism Detection + +**Module enhancement:** `encoach_ai_grading` (add plagiarism sub-service) + +### 30.1 Plagiarism Report Storage + +Add to `encoach.submission` or create `encoach.plagiarism.report`: + +| Field | Type | Description | +|-------|------|-------------| +| `submission_id` | Many2one | Target submission | +| `overall_score` | Float | AI probability score (0-1) | +| `per_sentence` | Text (JSON) | Per-sentence analysis from GPTZero | +| `report_pdf` | Binary | Generated PDF report | +| `checked_at` | Datetime | When check was run | + +### 30.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/plagiarism/check` | JWT (teacher) | Submit text for GPTZero analysis | +| `GET` | `/api/plagiarism/report/{submissionId}` | JWT | Get plagiarism report | +| `GET` | `/api/plagiarism/report/{submissionId}/download` | JWT | Download PDF report | + +### 30.3 Integration + +- Uses GPTZero `v2/predict/text` endpoint (already configured in `encoach_ai_grading`) +- Can be enabled/disabled per assignment via `plagiarism_enabled` boolean on `encoach.assignment` +- Configurable max submissions for plagiarism check via `plagiarism_max_checks` integer + +--- + +## 31. Official Exam Access + +**Module enhancement:** `encoach_exam` (add official access modes) + +### 31.1 Model Extensions + +Add to `encoach.exam`: + +| Field | Type | Description | +|-------|------|-------------| +| `is_exercise` | Boolean | Exercise (practice, no journey tracking) vs Exam | +| `is_official` | Boolean | Official exam flag | +| `access_mode` | Selection | `normal`, `link`, `landing_page`, `separate_login` | +| `access_token` | Char | Unique access token (auto-generated) | +| `access_code` | Char | Exam access code | +| `activation_start` | Datetime | Exam start time | +| `activation_end` | Datetime | Exam end time | +| `generate_unique_per_student` | Boolean | AI generates unique variant per student | +| `reminder_count` | Integer | Number of reminders to send | +| `reminder_frequency` | Selection | `once`, `daily`, `custom` | + +### 31.2 API Endpoints + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| `POST` | `/api/exam/{id}/generate-link` | JWT (teacher) | Generate unique access token/URL | +| `GET` | `/api/exam/access/{token}` | Public | Access exam via token (validates token, returns exam info) | +| `POST` | `/api/exam/official-login` | Public | Login with exam code + credentials | +| `POST` | `/api/exam/{id}/suspend` | JWT (teacher) | Suspend exam | +| `POST` | `/api/exam/{id}/revoke` | JWT (teacher) | Revoke exam access | + +--- + +## 32. Non-Functional Requirements + +### 32.1 Performance + +| ID | Requirement | +|----|-------------| +| NFR-PERF-01 | API response time < 500ms for CRUD endpoints | +| NFR-PERF-02 | AI endpoints may take up to 30s (use async job for long operations) | +| NFR-PERF-03 | Pagination: default `size=20`, max `size=100` | + +### 32.2 Security + +| ID | Requirement | +|----|-------------| +| NFR-SEC-01 | JWT tokens expire after 24 hours | +| NFR-SEC-02 | All endpoints validate entity-scoped permissions | +| NFR-SEC-03 | Rate limiting on AI endpoints (configurable) | +| NFR-SEC-04 | CORS configured for frontend origin | +| NFR-SEC-05 | File upload size limit: 50MB | +| NFR-SEC-06 | API keys stored in `ir.config_parameter`, never in code | + +### 32.3 Scalability + +| ID | Requirement | +|----|-------------| +| NFR-SCALE-01 | Support 10,000+ concurrent students | +| NFR-SCALE-02 | Support 50+ subjects, 500+ topics per subject, 1000+ resources per subject | +| NFR-SCALE-03 | Database indices on all foreign keys and frequently filtered fields | + +### 32.4 Reliability + +| ID | Requirement | +|----|-------------| +| NFR-REL-01 | AI service failures return graceful error (never 500) | +| NFR-REL-02 | Webhook processing is idempotent | +| NFR-REL-03 | Soft-delete for resources (preserve completion records) | + +### 32.5 API Conventions + +| Convention | Detail | +|-----------|--------| +| Date format | ISO 8601 (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`) | +| Pagination | `?page=1&size=20` returns `{ "items": [...], "total": N, "page": 1, "size": 20 }` | +| Error shape | `{ "error": "message", "code": "ERROR_CODE" }` with HTTP status | +| ID fields | Many2one serialized as `{field}_id` (int) + `{field}_name` (str) | +| List fields | Many2many serialized as `{field}_ids` (int[]) + `{field}_names` (str[]) | +| Binary fields | Base64-encoded strings or separate download endpoint | +| Auth header | `Authorization: Bearer ` | + +--- + +## 33. Implementation Status + +All modules have been implemented and deployed. The original priority ordering is preserved for reference. + +| Priority | Modules | Status | +|----------|---------|--------| +| **P0** | `encoach_core`, `encoach_api` (auth, users, entities, permissions) | **DONE** | +| **P0** | `openeducat_core` (port to v19), `encoach_lms_api` | **DONE** | +| **P1** | `encoach_taxonomy`, `encoach_adaptive`, `encoach_adaptive_api`, `encoach_adaptive_ai` | **DONE** | +| **P1** | `encoach_exam`, `encoach_ai_generation`, `encoach_ai_grading` | **DONE** | +| **P1** | `encoach_resources` | **DONE** | +| **P2** | `encoach_courseware` (chapters, materials, progress, AI workbench) | **DONE** | +| **P2** | `encoach_communication` (discussions, announcements, messaging) | **DONE** | +| **P2** | `openeducat_timetable`, `openeducat_attendance`, `openeducat_classroom` | **DONE** | +| **P2** | `openeducat_admission` + admission endpoints | **DONE** | +| **P2** | Academic years/terms, departments endpoints | **DONE** | +| **P2** | `encoach_ai`, `encoach_ai_media` | **DONE** | +| **P2** | `encoach_assignment`, `encoach_classroom` | **DONE** | +| **P3** | `encoach_notification` (rules, email delivery, preferences) | **DONE** | +| **P3** | Enhanced approval workflows (stages, escalation, bypass) | **DONE** | +| **P3** | Plagiarism detection (GPTZero integration) | **DONE** | +| **P3** | Official exam access modes (link, landing, separate login) | **DONE** | +| **P3** | Late submission handling, extension requests | **DONE** | +| **P3** | `openeducat_exam` + institutional exam endpoints | **DONE** | +| **P3** | `openeducat_assignment` + submission endpoints | **DONE** | +| **P3** | Subject registration endpoints | **DONE** | +| **P3** | `encoach_training`, analytics endpoints | **DONE** | +| **P3** | `encoach_sis`, `encoach_branding` | **DONE** | +| **P4** | `encoach_faq` (categories, items, role-filtered) | **DONE** | +| **P4** | `encoach_subscription` (Stripe, PayPal, Paymob) | **DONE** | +| **P4** | `encoach_ticket` | **DONE** | +| **P4** | Storage | **DONE** | + +--- + +## 34. Beyond-SRS Features (Implemented) + +The developer implemented the following features beyond the original SRS scope. These leverage OpenEduCat Enterprise modules and add significant institutional management capabilities. + +### 34.1 Student Leave Management + +**Module:** `openeducat_student_leave_enterprise` (via `encoach_lms_api`) +**Controller:** `encoach_lms_api/controllers/student_leave.py` +**Frontend:** `student-leave.service.ts` | `AdminStudentLeave.tsx` + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/student-leaves` | List leave requests | +| `POST` | `/api/student-leaves` | Create leave request | +| `PATCH` | `/api/student-leaves/{id}` | Update leave request | +| `POST` | `/api/student-leaves/{id}/approve` | Approve request | +| `POST` | `/api/student-leaves/{id}/reject` | Reject request | +| `GET` | `/api/student-leave-types` | List leave types | +| `POST` | `/api/student-leave-types` | Create leave type | + +### 34.2 Fees Management + +**Module:** `openeducat_fees` (via `encoach_lms_api`) +**Controller:** `encoach_lms_api/controllers/fees.py` +**Frontend:** `fees.service.ts` | `AdminFees.tsx` + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/fees-plans` | List fee plans | +| `GET` | `/api/fees-plans/{id}` | Fee plan detail | +| `GET` | `/api/student-fees` | Student fee details | +| `GET` | `/api/fees-terms` | Fee terms | + +### 34.3 Lessons Management + +**Module:** `openeducat_lesson` (via `encoach_lms_api`) +**Controller:** `encoach_lms_api/controllers/lessons.py` +**Frontend:** `lesson.service.ts` | `AdminLessons.tsx` + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/lessons` | List lessons | +| `POST` | `/api/lessons` | Create lesson | +| `PATCH` | `/api/lessons/{id}` | Update lesson | +| `DELETE` | `/api/lessons/{id}` | Delete lesson | + +### 34.4 Gradebook and Grading Assignments + +**Module:** `openeducat_grading` (via `encoach_lms_api`) +**Controller:** `encoach_lms_api/controllers/gradebook.py` +**Frontend:** `gradebook.service.ts` | `AdminGradebook.tsx` + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/gradebooks` | List gradebooks | +| `GET` | `/api/gradebook-lines` | Gradebook lines | +| `GET` | `/api/grading-assignments` | List grading assignments | +| `POST` | `/api/grading-assignments` | Create grading assignment | +| `PATCH` | `/api/grading-assignments/{id}` | Update grading assignment | +| `DELETE` | `/api/grading-assignments/{id}` | Delete grading assignment | + +### 34.5 Student Progress Tracking + +**Module:** `openeducat_student_progress_enterprise` (via `encoach_lms_api`) +**Controller:** `encoach_lms_api/controllers/student_progress.py` +**Frontend:** `student-progress.service.ts` | `AdminStudentProgress.tsx` + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/student-progress` | List student progression records | + +### 34.6 Library Management + +**Module:** `openeducat_library` (via `encoach_lms_api`) +**Controller:** `encoach_lms_api/controllers/library.py` +**Frontend:** `library.service.ts` | `AdminLibrary.tsx` + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/library/media` | List media items | +| `POST` | `/api/library/media` | Create media item | +| `DELETE` | `/api/library/media/{id}` | Delete media item | +| `GET` | `/api/library/movements` | List movements | +| `POST` | `/api/library/movements` | Create movement (issue) | +| `PATCH` | `/api/library/movements/{id}` | Update movement | +| `POST` | `/api/library/movements/{id}/return` | Return media | +| `GET` | `/api/library/cards` | List library cards | +| `POST` | `/api/library/cards` | Create library card | + +### 34.7 Activity Management + +**Module:** `openeducat_activity` (via `encoach_lms_api`) +**Controller:** `encoach_lms_api/controllers/activities.py` +**Frontend:** `activity.service.ts` | `AdminActivities.tsx` + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/activities` | List activities | +| `POST` | `/api/activities` | Create activity | +| `PATCH` | `/api/activities/{id}` | Update activity | +| `DELETE` | `/api/activities/{id}` | Delete activity | +| `GET` | `/api/activity-types` | List activity types | +| `POST` | `/api/activity-types` | Create activity type | +| `DELETE` | `/api/activity-types/{id}` | Delete activity type | + +### 34.8 Facility and Asset Management + +**Module:** `openeducat_facility` (extended via `encoach_lms_api`) +**Controller:** `encoach_lms_api/controllers/facilities.py` +**Frontend:** `facility.service.ts` | `AdminFacilities.tsx` + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/facilities` | List facilities | +| `POST` | `/api/facilities` | Create facility | +| `PATCH` | `/api/facilities/{id}` | Update facility | +| `DELETE` | `/api/facilities/{id}` | Delete facility | +| `GET` | `/api/assets` | List assets | +| `POST` | `/api/assets` | Create asset | +| `DELETE` | `/api/assets/{id}` | Delete asset | + +### 34.9 Roles CRUD, User Role Assignment, and Authority Matrix + +**Module:** `encoach_core` (extended) +**Controller:** `encoach_api/controllers/roles.py` +**Frontend:** `entities.service.ts` | `RolesPermissions.tsx`, `UserRoles.tsx`, `AuthorityMatrix.tsx` + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/roles` | List all roles | +| `POST` | `/api/roles` | Create role | +| `GET` | `/api/roles/{id}` | Get role detail | +| `PATCH` | `/api/roles/{id}` | Update role | +| `DELETE` | `/api/roles/{id}` | Delete role | +| `PATCH` | `/api/roles/{id}/permissions` | Update role permissions | +| `GET` | `/api/permissions` | List all permissions | +| `POST` | `/api/permissions` | Create permission | +| `DELETE` | `/api/permissions/{id}` | Delete permission | +| `GET` | `/api/users/with-roles` | List users with roles | +| `GET/PATCH` | `/api/users/{id}/roles` | Get/update user roles | +| `POST` | `/api/users/{id}/roles/toggle` | Toggle role for user | +| `GET` | `/api/authority-matrix` | Get role-permission matrix | +| `POST` | `/api/authority-matrix/toggle` | Toggle a matrix cell | +| `GET` | `/api/user-authority-matrix` | Get user-level authority | + +--- + +## Appendix A: Complete Endpoint Summary (Verified Against Deployment) + +Total API endpoints: **~377** (deployed across 4 controller packages) + +| Controller Package | Route Count | Service Areas | +|-------------------|-------------|---------------| +| `encoach_api` | ~120 | Auth, users, entities, roles, exams, assignments, classrooms, storage, stats, subscriptions, tickets, approvals, training, generation, AI analytics | +| `encoach_lms_api` | ~209 | Courses, students, teachers, batches, timetable, attendance, grades, departments, academic, admissions, subject registration, institutional exams, course assignments, student leave, fees, lessons, gradebook, student progress, library, activities, facilities, notifications, FAQ, courseware, plagiarism, communication, classrooms | +| `encoach_adaptive_api` | ~41 | Taxonomy (subjects, domains, topics), diagnostic, proficiency, learning plans, content, coaching | +| `encoach_resources` | ~7 | Learning resources (CRUD, download, complete, rate) | + +**Breakdown by Service Area:** + +| Service Area | Endpoint Count | Status | +|-------------|---------------|--------| +| Auth & Users | 10 | Deployed | +| Entities & Permissions | 9 | Deployed | +| Roles CRUD & Authority Matrix | 12 | **Deployed (Beyond SRS)** | +| LMS (Courses, Batches, Timetable, Attendance, Grades) | 16 | Deployed | +| Academic Years, Terms, Departments | 14 | Deployed | +| Admissions | 12 | Deployed | +| Subject Registration | 6 | Deployed | +| EnCoach Exams (AI) | 15 | Deployed | +| Institutional Exams | 21 | Deployed | +| EnCoach Assignments | 7 | Deployed | +| Course Assignments & Submissions | 11 | Deployed | +| Classrooms & Groups | 7 | Deployed | +| Taxonomy | 16 | Deployed | +| Adaptive Learning | 17 | Deployed | +| Resources | 7 | Deployed | +| AI Coaching | 6 | Deployed | +| AI Evaluation | 4 | Deployed | +| AI Generation | 2 | Deployed | +| AI Media | 3 | Deployed | +| AI Analytics | 6 | Deployed | +| Training | 3 | Deployed | +| Statistics | 4 | Deployed | +| Subscriptions & Payments | 8 + 3 webhooks | Deployed | +| Tickets | 4 | Deployed | +| Storage | 2 | Deployed | +| Approval Workflows (Enhanced) | 11 | Deployed | +| Courseware (Chapters + Materials + Workbench) | 23 | Deployed | +| Discussion Boards + Posts | 9 | Deployed | +| Announcements | 5 | Deployed | +| Messaging | 6 | Deployed | +| Notifications + Rules + Preferences | 10 | Deployed | +| FAQ (Categories + Items) | 8 | Deployed | +| Plagiarism Detection | 3 | Deployed | +| Official Exam Access | 5 | Deployed | +| Student Leave Management | 7 | **Deployed (Beyond SRS)** | +| Fees Management | 4 | **Deployed (Beyond SRS)** | +| Lessons Management | 4 | **Deployed (Beyond SRS)** | +| Gradebook & Grading | 6 | **Deployed (Beyond SRS)** | +| Student Progress | 1 | **Deployed (Beyond SRS)** | +| Library Management | 9 | **Deployed (Beyond SRS)** | +| Activity Management | 7 | **Deployed (Beyond SRS)** | +| Facility & Asset Management | 7 | **Deployed (Beyond SRS)** | + +--- + +## Appendix B: Model Relationship Diagram + +``` +res.users ──extends──> encoach.user + │ │ + │ ├── entity_ids ──> encoach.entity + │ │ └── role_ids ──> encoach.role + │ │ └── permission_ids ──> encoach.permission + │ │ + │ ├── op_student_id ──> op.student ──> op.student.course ──> op.course + │ │ ├── op.batch + │ │ ├── op.subject + │ │ └── op.department + │ │ + │ └── op_faculty_id ──> op.faculty + │ + ├── encoach.exam ──> encoach.subject (taxonomy) + │ ├── encoach.domain + │ │ └── encoach.topic + │ │ ├── encoach.learning.objective + │ │ ├── encoach.proficiency + │ │ └── encoach.resource + │ │ + │ └── encoach.learning.plan + │ └── encoach.learning.plan.item ──> encoach.topic + │ + ├── op.academic.year ──> op.academic.term + │ + ├── op.admission.register ──> op.admission ──> op.student + │ + ├── op.exam.session ──> op.exam ──> op.exam.attendees + │ └── op.marksheet.register ──> op.marksheet.line + │ + ├── op.assignment ──> op.assignment.sub.line (submissions) + │ + ├── encoach.course.chapter ──> op.course + │ ├── encoach.chapter.material + │ ├── encoach.chapter.progress ──> res.users + │ └── encoach.topic (bridge to adaptive) + │ + ├── encoach.discussion.board ──> op.course / op.batch / encoach.course.chapter + │ └── encoach.discussion.post (self-referencing for threads) + │ + ├── encoach.announcement ──> op.course / op.batch + │ + ├── encoach.message ──> res.users (sender/recipient) + │ + ├── encoach.notification ──> res.users + │ └── encoach.notification.rule (event triggers) + │ + ├── encoach.faq.category ──> encoach.faq.item + │ + ├── encoach.approval.workflow ──> encoach.approval.stage + │ └── encoach.approval.request + │ + └── encoach.plagiarism.report ──> submission +``` + +--- + +*This SRS is the definitive backend specification for the EnCoach platform on Odoo 19. All ~377 REST API endpoints, 41 Odoo modules (14 OpenEduCat + 27 custom), and all AI service integrations have been implemented and deployed to staging at `http://5.189.151.117:8069`. All previous backend SRS documents (`ODOO_BACKEND_SRS_v3.md`, `ODOO_MIGRATION_SRS_v2.md`, `ODOO_MIGRATION_SRS.md`) are superseded by this document.* diff --git a/docs/ENCOACH_PRODUCT_DESCRIPTION.md b/docs/ENCOACH_PRODUCT_DESCRIPTION.md new file mode 100644 index 00000000..805912a1 --- /dev/null +++ b/docs/ENCOACH_PRODUCT_DESCRIPTION.md @@ -0,0 +1,186 @@ +# EnCoach -- Product Description + +**Prepared for:** UTAS University Management +**Date:** March 24, 2026 +**Version:** 1.0 +**Classification:** Client-Facing + +--- + +## 1. Executive Summary + +EnCoach is an AI-powered adaptive learning platform designed to deliver personalized education across multiple academic subjects. The platform automatically assesses each student's current knowledge level, generates a tailored learning plan, delivers the right content at the right time, and continuously adjusts as the student progresses. EnCoach serves two distinct audiences -- **UTAS-enrolled students** who follow university curriculum with AI-enhanced guidance, and **freelance learners** worldwide who access fully AI-driven self-paced programs. The platform launches with three subjects -- **IELTS/English, Mathematics, and Information Technology** -- and is designed to accommodate any additional subject without rebuilding the system. + +--- + +## 2. Product Vision + +### The Problem + +Traditional learning platforms deliver the same material to every student regardless of their existing knowledge. Students waste time reviewing topics they already understand, while critical gaps in their foundation go unaddressed. Teachers lack visibility into individual student needs at scale, and institutions struggle to provide personalized learning outside the classroom. + +### The Solution + +EnCoach combines a proven Learning Management System with an intelligent adaptive engine that treats every student as an individual. The platform: + +- **Discovers what each student knows** through an AI-driven diagnostic assessment +- **Builds a personalized roadmap** that prioritizes weak areas while respecting how topics build on each other +- **Delivers the right content** -- human-curated materials when available, AI-generated explanations when not +- **Adapts in real time** -- as students learn faster or struggle, the plan adjusts automatically +- **Provides an AI coaching companion** available on every page for hints, explanations, and study advice + +### Strategic Value for UTAS + +| Value | Description | +|-------|-------------| +| **Scalable personalization** | Every UTAS student receives an individualized learning experience without increasing teaching staff | +| **Multi-subject from day one** | English, Math, and IT share a single platform; new subjects can be added by defining a topic structure | +| **Revenue expansion** | Freelance students outside UTAS generate subscription revenue on the same platform | +| **Data-driven insights** | Real-time analytics show administrators exactly where students succeed or struggle, per topic, per class, per department | +| **Quality assurance** | AI-generated content is supplementary -- academic staff control the primary learning materials and approve AI outputs | + +--- + +## 3. Key Capabilities + +### 3.1 Adaptive Learning Engine + +The core innovation of EnCoach. When a student begins a new subject, the platform runs an intelligent diagnostic that adapts in real time -- asking harder questions when answers are correct and easier ones when they are not. Within minutes, the system maps the student's strengths and weaknesses across every topic in the subject. + +From this assessment, the AI generates a **personalized learning plan**: a sequenced path through topics the student needs to study, ordered so that foundational concepts are learned before advanced ones. As the student works through the plan, short mastery quizzes confirm understanding before moving on. If a student struggles, the system provides additional resources and intensifies AI coaching. If they progress quickly, the plan accelerates. + +**For UTAS students**, the learning plan aligns with the university's curriculum and semester schedule. Teachers can view and override individual plans. **For freelance students**, the AI generates the complete plan independently based on the student's goals and timeline. + +### 3.2 Multi-Subject Support + +EnCoach is not a single-purpose English testing tool -- it is a universal education platform. Every subject is organized into the same clear hierarchy: + +- **Subject** (e.g., Mathematics) + - **Domain** (e.g., Algebra) + - **Topic** (e.g., Linear Equations) + +This structure supports any academic discipline. The platform launches with: + +| Subject | Coverage | +|---------|----------| +| **IELTS / English** | Reading, Listening, Writing, Speaking, Grammar, Vocabulary, Pronunciation | +| **Mathematics** | Arithmetic, Algebra, Geometry, Statistics & Probability, Calculus | +| **Information Technology** | Computer Fundamentals, Networking, Databases, Programming, Cybersecurity | + +Adding a new subject (e.g., Arabic, Physics, Business) requires only defining its topic structure -- the adaptive engine, exam system, grading, and analytics apply automatically. + +### 3.3 Learning Management System + +A full-featured LMS for structured academic delivery: + +- **Course management** -- Create courses with modules and lessons, assign instructors, set enrollment limits +- **Student enrollment** -- UTAS students enrolled automatically via SIS sync; freelance students self-enroll +- **Batches** -- Group students for cohort-based learning and shared schedules +- **Timetable** -- Schedule and display class sessions for students, teachers, and administrators +- **Attendance** -- Teachers record attendance; students view their own records; administrators monitor patterns +- **Gradebook** -- Centralized grade management with AI-generated narrative reports for academic reviews + +### 3.4 Exam Engine + +A powerful assessment system that goes far beyond multiple-choice: + +- **AI-generated exams** -- The platform creates new exam content on demand for any subject and difficulty level. English exams include reading passages, listening scripts, writing tasks, and speaking prompts. Math exams include numerical problems, word problems, and multi-step worked problems. IT exams include code completion, scenario-based questions, and true/false items. +- **AI-powered grading** -- Writing and speaking responses are graded automatically against detailed rubrics. Math answers are checked with numerical tolerance. IT code answers are evaluated for correctness and approach. All AI grades can be reviewed and approved by teachers through an approval workflow. +- **AI writing detection** -- Every written submission is scanned for AI-generated content, providing per-sentence confidence scores. +- **Multiple delivery modes** -- Practice exams, timed official exams, scheduled assignments, diagnostic assessments, and mastery quizzes. + +### 3.5 AI Assistant + +An intelligent companion embedded throughout the platform: + +| What It Does | Where | +|-------------|-------| +| **Answers questions** in natural language about any topic | Available on every page via a chat drawer | +| **Gives hints** during practice exercises without revealing the answer | Practice and study pages | +| **Explains grades** so students understand what to improve | After exam results | +| **Suggests what to study next** based on progress and weaknesses | Student dashboard | +| **Generates study tips** personalized to the student's current topic | Topic learning pages | +| **Helps teachers create content** -- course outlines, assignments, rubrics | Teacher course builder | +| **Produces report narratives** for academic reviews | Admin reports | +| **Flags at-risk students** based on attendance, grades, and engagement patterns | Teacher and admin dashboards | + +### 3.6 Administration and Reporting + +Comprehensive tools for managing the platform at every level: + +- **User management** -- Create, search, filter, and export student, teacher, and corporate accounts +- **Multi-tenant organizations** -- Each institution or company operates in its own space with its own roles, permissions, and branding +- **Classroom management** -- Create student groups, transfer students between classes +- **Assignment scheduling** -- Schedule exams with start/end dates, assign to classrooms or individual students, track completion +- **Permission system** -- Granular control over who can view, create, edit, or delete content, organized by subject +- **Analytics dashboards** -- Real-time metrics on student performance, subject completion rates, AI usage, content gaps, and resource utilization +- **Support ticketing** -- Built-in helpdesk for students and staff to report issues +- **Payment management** -- Institutional licensing for UTAS, individual subscriptions for freelance students, with support for multiple payment providers + +--- + +## 4. User Experience + +### The Student Experience + +A student logs in and sees their personalized dashboard: current subjects, learning plan progress, upcoming assignments, and a study streak counter. They select a subject and see their mastery profile -- a visual map showing which topics they have mastered, which they are working on, and which are locked until prerequisites are completed. Clicking a topic opens the learning page with curated materials (PDFs, videos, articles) and AI-generated explanations. After studying, a short mastery quiz confirms understanding. Throughout the experience, the AI coach is always available for hints, explanations, and encouragement. The student can also attend scheduled classes, view their timetable, check grades, and track attendance -- all from a single, unified interface. + +### The Teacher Experience + +A teacher logs in to see their class dashboard with insights at a glance: which students are progressing, which are at risk, and where content gaps exist. They can create courses using the AI course builder that generates outlines from a topic description. When grading, the AI Grading Assistant suggests marks and provides feedback drafts that the teacher can accept, modify, or override. Teachers can view any student's learning plan, adjust it if needed, and monitor mastery across their entire class through a heatmap visualization. Attendance recording and timetable management are integrated directly into their workflow. + +### The Administrator Experience + +An administrator has full visibility across the entire platform. The LMS dashboard shows enrollment numbers, completion rates, and subject-level performance across all courses. The platform dashboard provides user counts, entity statistics, and system health. Administrators manage organizations, roles, and permissions; they create exam structures, configure approval workflows, and oversee the content library. AI-powered reports generate narrative summaries for academic reviews, and the batch optimizer suggests class compositions for balanced learning outcomes. + +--- + +## 5. How AI Powers the Platform + +EnCoach integrates six specialized AI capabilities, each designed for a specific educational purpose: + +| Capability | What It Does for Users | +|-----------|----------------------| +| **Intelligent Conversation** | Powers the AI Assistant, the study coach, grade explanations, writing help, and content generation. Understands context -- it knows what page you are on, what topic you are studying, and what your recent performance looks like. | +| **Speech Recognition** | Converts student voice recordings into text for speaking exam grading. Supports multiple accents and speaking styles. | +| **Text-to-Speech** | Generates natural-sounding audio for English listening exams. Supports 11 distinct voices with regional accents for authentic test preparation. | +| **AI Video Avatars** | Creates video-based speaking prompts with realistic virtual presenters, making speaking practice more engaging and exam-like. | +| **Content Authenticity** | Scans written submissions to detect AI-generated text, ensuring academic integrity with per-sentence confidence analysis. | +| **Smart Recommendations** | Finds the most relevant training tips, study materials, and content recommendations based on semantic understanding of each student's needs -- not just keyword matching. | + +All AI-generated content is supplementary. Academic staff control primary learning materials, and AI outputs can be routed through approval workflows before students see them. + +--- + +## 6. Integration with UTAS + +| Integration Area | How It Works | +|-----------------|-------------| +| **Student Information System (SIS)** | Student enrollment data syncs automatically from UTAS SIS. New students appear in EnCoach without manual data entry. Student records stay synchronized throughout the semester. | +| **Curriculum Alignment** | Learning plans for UTAS students follow the university's curriculum. The topic taxonomy maps to UTAS course structures, ensuring adaptive learning enhances rather than replaces the academic program. | +| **Institutional Licensing** | UTAS operates under an institutional license covering all enrolled students and staff. No individual subscriptions needed for university members. | +| **Teacher and Admin Oversight** | UTAS teachers see their students' AI-generated learning plans and can adjust them. Administrators have full visibility into performance analytics across all departments and subjects. | +| **Branding** | The platform can display UTAS branding (logo, colors) for an institution-native experience. | + +--- + +## 7. Platform at a Glance + +| Dimension | Details | +|-----------|---------| +| **Subjects** | IELTS/English, Mathematics, Information Technology (extensible to any subject) | +| **User Roles** | Student, Teacher, Admin, Corporate, Master Corporate, Agent, Developer | +| **Student Modes** | UTAS Institutional (SIS-synced, curriculum-aligned) and Freelance (self-registered, AI-guided) | +| **AI Capabilities** | Adaptive diagnostics, personalized learning plans, content generation, automated grading, real-time coaching, writing integrity detection | +| **LMS Features** | Courses, batches, timetable, attendance, gradebook, reporting | +| **Exam Types** | Practice, official, assignment-based, diagnostic, mastery quiz | +| **Content Model** | Hybrid -- human-uploaded resources prioritized, AI-generated content fills gaps | +| **Payment Options** | Institutional license, individual subscription, bundled packages | +| **Payment Providers** | Stripe, PayPal, Paymob | +| **Security** | Server-side authorization, role-based access control, encrypted authentication, data isolation between organizations | +| **Deployment** | Cloud-hosted, containerized architecture, automated scaling | +| **Accessibility** | Responsive design (desktop and mobile), accessible form controls, screen reader support | + +--- + +*This document describes the EnCoach platform as specified in the Unified Platform SRS (v1.0, March 2026). For detailed technical specifications, refer to ENCOACH_UNIFIED_SRS.md.* diff --git a/docs/ENCOACH_SYSTEM_FEATURES_GUIDE.md b/docs/ENCOACH_SYSTEM_FEATURES_GUIDE.md new file mode 100644 index 00000000..6ebba0b4 --- /dev/null +++ b/docs/ENCOACH_SYSTEM_FEATURES_GUIDE.md @@ -0,0 +1,308 @@ +# EnCoach Platform -- System Features Guide + +**Version:** 1.0 +**Date:** March 2026 +**Purpose:** Describe every section and feature accessible through the platform navigation, organized by user role. + +--- + +## Part 1: Administrator Panel + +The Administrator Panel is the central management hub for the entire platform. It is accessible to users with roles: Admin, Corporate, Master Corporate, Agent, and Developer. + +--- + +### 1. Overview + +The Overview section provides high-level dashboards that give administrators an at-a-glance view of the entire platform's health and activity. + +| Menu Item | Description | +|-----------|-------------| +| **Admin Dashboard** | The LMS-focused dashboard showing real-time counts of courses, students, teachers, batches, and enrollment status. Displays course capacity charts, student status distribution, and recent activity. | +| **Platform Dashboard** | The original platform dashboard focused on exam and assignment activity. Shows exam creation statistics, assignment completion rates, user activity trends, and entity-level performance summaries. | + +--- + +### 2. LMS + +The LMS (Learning Management System) section is the core of institutional course management. It handles the full lifecycle of courses, students, teachers, and class scheduling. + +| Menu Item | Description | +|-----------|-------------| +| **Courses** | Create, view, and manage courses. Each course has a title, code, description, maximum capacity, status (draft/active/archived), and is linked to a department. Administrators can view enrollment counts and manage course settings. | +| **Students** | Manage student records. Create new students (which automatically creates a portal user account), view student lists with filters, export student data, and manage individual student profiles including their course enrollments. | +| **Teachers** | Manage teacher records. Create teacher profiles with specialization areas, link them to portal user accounts, assign them to courses and batches, and view their teaching schedules. | +| **Batches** | Manage class batches (sections/cohorts). Each batch belongs to a course and has a date range, capacity, and enrolled students. Administrators can view batch details, manage student enrollment per batch, and track batch capacity. | +| **Lessons** | Create and manage individual lessons linked to a course, batch, and subject. Each lesson has a faculty member, date, and duration. Used to organize the day-to-day teaching schedule within a course. | +| **Timetable** | Visual timetable management with a day/time grid. Create, view, and delete teaching sessions. Sessions are linked to courses, batches, subjects, and classrooms with specific day and time slots. | +| **Reports** | LMS-specific reporting dashboards showing course enrollment trends, batch capacity utilization, student status distributions, teacher workload, and overall LMS usage analytics. | + +--- + +### 3. Adaptive Learning + +The Adaptive Learning section manages the AI-powered personalized learning engine. It controls the knowledge structure that drives diagnostic tests, proficiency tracking, and personalized learning plans. + +| Menu Item | Description | +|-----------|-------------| +| **Taxonomy** | Manage the subject knowledge hierarchy: Subjects (e.g., English, Math, IT) contain Domains, which contain Topics, which contain Learning Objectives. This taxonomy drives the adaptive engine -- diagnostic tests assess proficiency at the topic level, and learning plans are generated based on this structure. Administrators can create subjects, add domains/topics manually, or use AI to suggest topic structures. | +| **Resources** | Manage the learning resource library. Upload educational materials (PDFs, videos, links, documents, interactive content) and tag them to specific topics in the taxonomy. Resources go through a review workflow (pending, approved, rejected) and are served to students through their personalized learning plans. Track resource downloads, completion, and ratings. | + +--- + +### 4. Institutional + +The Institutional section handles university-level academic administration -- the calendar, departments, enrollment pipeline, formal exam sessions, grading, and student lifecycle. + +| Menu Item | Description | +|-----------|-------------| +| **Academic Years** | Define academic years with start and end dates. Auto-generate academic terms (semesters/quarters) within each year. Academic years organize all institutional activities -- courses, batches, exams, and grades are all scoped to an academic year. | +| **Departments** | Manage the department hierarchy with parent-child relationships. Departments organize courses and faculty. Each department can have sub-departments, a head of department, and associated courses. | +| **Admissions** | View and process individual student admission applications. Each admission goes through a workflow: submitted, confirmed, admitted, or rejected. Administrators can review application details, update status, and convert admitted applicants into enrolled students. | +| **Admission Register** | Manage admission campaigns/registers. Each register defines an admission period (open/closed), linked course, available seats, and start/end dates. Registers go through a workflow: create, confirm (open for applications), close (stop accepting). | +| **Exam Sessions** | Schedule and manage institutional exam sessions. Each session is linked to a course, batch, and academic term. Sessions go through a workflow: draft, scheduled, in progress, done. Manage exam rooms, attendees, and timing within each session. | +| **Marksheets** | Generate and validate student marksheets (grade reports). Marksheets aggregate student scores across exams within a session, apply grade configurations and result templates, and compute pass/fail status. Supports validation workflow before official release. | +| **Student Leave** | Manage student leave requests. Students submit leave requests with reasons and dates; administrators or teachers can approve or reject them. Tracks leave history per student. | +| **Fees** | View fee plans, fee terms, and individual student fee records. Manage fee structures attached to courses, including installment plans and payment tracking. | +| **Gradebook** | View and manage the institutional grading system. Displays grades per student, per course, and per academic year. Supports grading assignment types, weighted grading, and grade configuration (letter grades, percentage scales). | +| **Student Progress** | Track longitudinal student progress across courses, subjects, and academic terms. Provides a historical view of student performance, showing trends and areas that need attention. | + +--- + +### 5. Academic + +The Academic section manages the AI-powered exam engine -- creating exams, defining grading rubrics, generating content with AI, and managing the approval workflow for publishing exams. + +| Menu Item | Description | +|-----------|-------------| +| **Assignments** | Create and manage exam-linked assignments. Each assignment wraps an exam and assigns it to specific students or classrooms with deadlines. Supports tabs for Active, Planned, Past, and Archived assignments. Includes late submission policies, extension requests, penalty configuration, and reminder settings. | +| **Exams List** | Browse, search, and manage all exams in the system. Filter by subject, module (Reading, Writing, Listening, Speaking), and difficulty. Each exam contains exercises, passages, timer settings, and access controls (public/private). Supports both practice exercises and official exams. | +| **Exam Structures** | Define exam blueprints (templates) that specify the section layout of exams -- how many sections, what type of questions in each, difficulty distribution, and time allocation per section. Structures are reusable across multiple exams. | +| **Rubrics** | Create and manage grading rubrics that define the criteria for evaluating student responses. Rubrics specify scoring dimensions (e.g., Task Achievement, Coherence, Grammar for IELTS writing). Rubric groups organize related rubrics. Used by both human graders and the AI grading engine. | +| **Generation** | The AI exam generation interface. Select a subject, module, and topic; configure difficulty and question types; and let the AI (GPT-4o) generate complete exams with passages, questions, and answer keys. Supports generation from scratch or from existing content. | +| **Approval Workflows** | Manage the approval process for publishing exams and course materials. Configure multi-stage workflows with specific approvers, time limits per stage, auto-escalation rules, and bypass options. Track approval status (pending, approved, rejected, escalated) with comments through each stage. | + +--- + +### 6. Management + +The Management section handles platform-wide user, organization, and infrastructure management. + +| Menu Item | Description | +|-----------|-------------| +| **Users** | Full user management. Create, update, search, filter, and export users. View user details including role, entity, verification status, and activity history. Supports batch user import from spreadsheets. | +| **Entities** | Manage organizations (multi-tenant). Each entity is an institution or company using the platform. Configure entity settings, manage entity-specific roles and permissions, generate invite codes for onboarding, and set per-entity branding (logo, colors). | +| **Classrooms** | Manage virtual and physical classroom groups. Create classrooms with capacity tracking, assign students to classrooms, and use classrooms for assigning exams and assignments to groups of students. | +| **Roles & Permissions** | Create and manage roles within entities. Each role has a name and a set of granular permissions. Administrators can create custom roles, assign/remove permissions from roles, and manage the permission catalog. | +| **Authority Matrix** | A cross-reference visualization of all roles and their permissions. Displayed as an interactive grid where rows are roles and columns are permissions. Administrators can toggle permissions on/off directly from the matrix view. | +| **User Roles** | Assign roles to individual users. View all users with their current role assignments, search and filter, and assign or remove roles. Supports user-level permission overrides beyond their assigned role. | + +--- + +### 7. Reports + +The Reports section provides analytical views of platform performance and student outcomes. + +| Menu Item | Description | +|-----------|-------------| +| **Student Performance** | Detailed performance analytics per student. Shows exam scores, assignment completion rates, proficiency levels across subjects, and trends over time. Supports filtering by entity, course, and date range. | +| **Stats Corporate** | Entity-level statistics for corporate/institutional managers. Shows aggregated data across all students within an entity -- enrollment counts, average scores, completion rates, and comparative performance across courses. | +| **Record** | Historical activity records. Browse past exam sessions, assignment submissions, and user activity logs. Supports searching and filtering by date, user, and activity type. | + +--- + +### 8. Configuration + +The Configuration section manages platform-wide settings for notifications, FAQs, and approval processes. + +| Menu Item | Description | +|-----------|-------------| +| **FAQ Manager** | Create and manage Frequently Asked Questions. Organize FAQs into categories, set target audience per item (student, entity, or both), add rich content including text, images, and video links. FAQs are displayed on a public searchable page with accordion-style expand/collapse. | +| **Notification Rules** | Configure automated notification triggers. Define rules based on event types (assignment due, exam due, chapter unlock, result release), set timing (how many days before the event), frequency (once, daily, custom intervals), and delivery channel (in-app, email, or both). | +| **Approval Config** | Configure the enhanced approval workflow system. Define multi-stage approval templates with specific approvers per stage, maximum days before auto-escalation, notification emails, and bypass permissions. Applied to exam publishing and course material approval. | + +--- + +### 9. Training + +The Training section provides reference materials for language learning support. + +| Menu Item | Description | +|-----------|-------------| +| **Vocabulary** | Browse vocabulary training content. Displays categorized vocabulary lists, definitions, usage examples, and related exercises. Linked to the FAISS-based recommendation engine for contextual suggestions. | +| **Grammar** | Browse grammar training content. Displays grammar rules, examples, common mistakes, and practice exercises organized by topic and difficulty level. | + +--- + +### 10. Support + +The Support section handles financial tracking, user support, and system settings. + +| Menu Item | Description | +|-----------|-------------| +| **Payment Record** | View payment history and transaction records. Shows all subscription payments, amounts, providers (Stripe/PayPal/Paymob), status, and associated packages. Supports filtering by date, user, and payment status. | +| **Tickets** | Manage support tickets. View all tickets submitted by users, assign tickets to support agents, update ticket status (open, in progress, resolved, closed), and communicate with ticket reporters. | +| **Settings** | Platform-wide settings management. Configure system parameters, AI service settings (API keys stored securely), default behaviors, and platform-level preferences. | + +--- + +### 11. Other Admin Pages (Accessible but not in main sidebar) + +| Page | Description | +|------|-------------| +| **Library** | Manage the institutional library. CRUD operations for library media (books, journals, digital resources), track media movements (issue, return), and manage student library cards. | +| **Activities** | Log and track student activities. Define activity types and record student participation in extracurricular or academic activities outside the standard course structure. | +| **Facilities** | Manage institutional facilities and assets. Track rooms, equipment, and other physical resources used for teaching and examinations. | + +--- + +## Part 2: Teacher Panel + +The Teacher Panel provides instructors with tools to manage their courses, create content, track student progress, and communicate with their classes. + +--- + +### 1. Teaching + +The Teaching section is the teacher's primary workspace for delivering courses and managing assignments. + +| Menu Item | Description | +|-----------|-------------| +| **Dashboard** | The teacher's home screen showing an overview of their assigned courses, upcoming assignments, recent student submissions, and quick statistics (number of students, pending grading, upcoming sessions). | +| **Courses** | View and manage assigned courses. From here, teachers can access three key sub-pages per course: **Chapters** (organize course content into sequential chapters with materials, set unlock dates, and control access), **Chapter Detail** (upload and manage materials within a chapter -- PDFs, videos, audio, images, links -- with download permission controls), and **AI Workbench** (generate course content using AI by inputting topic, objectives, and complexity level; review and publish AI-generated chapters, materials, exercises, and rubrics). | +| **Assignments** | Create and manage assignments for classes. Define deadlines, late submission policies, penalty structures, and reminder frequencies. View assignment submissions, check plagiarism reports, grade with AI assistance, and release results. Drill into individual assignments to see per-student submission status and grading. | + +--- + +### 2. Management + +The Management section gives teachers tools to track student attendance and schedules. + +| Menu Item | Description | +|-----------|-------------| +| **Attendance** | Take and manage attendance for classes. Mark students as present, absent, or late for each session. View attendance history and trends per batch. | +| **Students** | View the list of students enrolled in the teacher's courses and batches. Access individual student profiles and performance summaries. | +| **Timetable** | View the teacher's personal teaching schedule in a visual day/time grid format. Shows all assigned sessions across courses and batches. | + +--- + +### 3. Communication + +The Communication section enables teacher-student interaction and class announcements. + +| Menu Item | Description | +|-----------|-------------| +| **Discussions** | View and manage discussion boards for courses. Teachers can enable/disable discussion boards per course or chapter, create discussion threads, reply to student questions, pin important posts, and mark questions as resolved. Supports file attachments. | +| **Announcements** | Create and broadcast announcements to classes. Set priority (normal, important, urgent), target specific courses or batches, optionally send via email in addition to in-app notification. Manage drafts and publish when ready. | + +--- + +### 4. Account + +| Menu Item | Description | +|-----------|-------------| +| **Profile** | View and update personal profile information (name, email, specialization, contact details). | + +--- + +## Part 3: Student Panel + +The Student Panel provides learners with access to their courses, adaptive learning engine, progress tracking, and communication tools. + +--- + +### 1. Learning + +The Learning section is the student's primary workspace for accessing courses and completing assignments. + +| Menu Item | Description | +|-----------|-------------| +| **Dashboard** | The student's home screen showing enrolled subjects, upcoming deadlines (assignments, quizzes, exams), recent announcements, personal progress statistics, and AI study tips. Includes an AI coaching assistant for on-demand help. | +| **My Courses** | Browse all enrolled courses. Each course shows its chapters, completion progress, and available materials. Students can navigate into individual courses to see the chapter structure, access unlocked chapter content, download materials (when permitted by the teacher), and track their progress through the course. | +| **Subject Registration** | Register for available subjects within the current academic term. View available subjects, prerequisites, and capacity. Submit registration requests for subjects the student wants to take. | +| **Assignments** | View all active, upcoming, and past assignments. Submit completed work through the platform, view deadlines and submission status, request deadline extensions (when allowed), track submission history, and receive AI-generated feedback and plagiarism reports. | + +--- + +### 2. Adaptive Learning + +The Adaptive Learning section provides AI-powered personalized education that adapts to each student's level. + +| Menu Item | Description | +|-----------|-------------| +| **My Subjects** | The entry point for the adaptive learning engine. Displays all subjects the student is studying with their overall mastery level. From here, students can: take a **Diagnostic Test** (AI-administered assessment to determine initial proficiency across topics), view their **Proficiency Profile** (detailed breakdown of mastery per topic within a subject), access their **Learning Plan** (AI-generated personalized study path with ordered topics based on proficiency gaps), and study individual **Topics** (AI-curated learning content with practice exercises and mastery quizzes that adapt difficulty based on performance). | + +--- + +### 3. Progress + +The Progress section shows academic performance, attendance, and the overall learning journey. + +| Menu Item | Description | +|-----------|-------------| +| **Grades** | View grades for all courses, assignments, and exams. Shows current marks, feedback from teachers, and detailed score breakdowns by grading criteria. | +| **Attendance** | View personal attendance records across all enrolled courses. Shows attendance percentage, absent dates, and any leave requests with their approval status. | +| **Timetable** | View personal class schedule in a visual day/time grid. Shows all upcoming sessions with course, subject, teacher, and room information. | +| **My Journey** | A longitudinal progress timeline showing the student's overall academic journey. Displays enrolled courses with completion percentages, per-subject proficiency trends, and a recent activity timeline (exams taken, assignments submitted, chapters completed). Provides a holistic view of growth over time. | + +--- + +### 4. Communication + +The Communication section enables students to interact with teachers and classmates. + +| Menu Item | Description | +|-----------|-------------| +| **Discussions** | Participate in course and chapter discussion boards. Create new discussion threads, reply to existing threads (nested replies), ask questions about assignments or course content, and view pinned/resolved posts. Students can see other participants within the same class. | +| **Messages** | Direct messaging between users. View inbox (with read/unread indicators and unread count badge), send messages to teachers or classmates within the same class, attach files, and optionally send an email copy. Includes a sent messages view. | +| **Announcements** | View announcements from teachers and system administrators. Announcements are displayed with priority indicators (urgent, important, normal) and sorted by date. | + +--- + +### 5. Account + +| Menu Item | Description | +|-----------|-------------| +| **Profile** | View and update personal profile information (name, email, contact details, preferences). | + +--- + +## Part 4: Public Pages (No Login Required) + +These pages are accessible without authentication. + +| Page | Description | +|------|-------------| +| **Login** | User authentication with email and password. Redirects to the appropriate dashboard based on user role after successful login. | +| **Register** | New user registration. Supports open registration or invite-code-based registration to join a specific entity with a predefined role. | +| **Forgot Password** | Password recovery via email. Users enter their email to receive a verification link for password reset. | +| **Admission Application** | Public admission form for prospective students. Users can apply to an open admission register without logging in, providing personal details and required documents. They can check application status afterward. | +| **FAQ** | Public Frequently Asked Questions page. Searchable, accordion-style display of FAQ items organized by category. Content is filtered based on the user's role (student or entity) if logged in, showing all items if accessed publicly. | +| **Official Exam Access** | Special exam access pages for official/proctored exams. Supports three modes: (1) token-based link access where students open a unique URL, (2) landing page access with an exam code, and (3) a dedicated exam login screen isolated from the rest of the platform. | + +--- + +## Part 5: AI Features (Embedded Across the Platform) + +AI capabilities are embedded throughout the platform rather than being a standalone section. Here is where AI appears: + +| Feature | Where It Appears | What It Does | +|---------|-----------------|-------------| +| **AI Study Coach** | Student Dashboard | Chat-based coaching assistant that provides hints, concept explanations, writing help, and study tips. | +| **AI Exam Generation** | Admin > Generation, Teacher > AI Workbench | Generates complete exams (passages, questions, answer keys) from subject taxonomy using GPT-4o. | +| **AI Grading** | Admin > Assignments, Teacher > Assignments | Automatically grades writing (rubric-based IELTS band scoring), speaking (transcription + evaluation), math (step evaluation), and IT (code evaluation) using GPT-4o. | +| **AI Course Content** | Teacher > AI Workbench | Generates course outlines, chapter content, exercises, and grading rubrics from high-level requirements. | +| **AI Diagnostics** | Student > My Subjects | Administers adaptive diagnostic tests that adjust question difficulty based on responses to accurately assess proficiency. | +| **AI Learning Plans** | Student > My Subjects | Generates personalized learning plans based on diagnostic results and proficiency gaps. | +| **AI Content Recommendations** | Student > Topic Learning | Suggests additional learning materials based on student performance and learning history using FAISS similarity search. | +| **AI Plagiarism Detection** | Teacher > Assignments, Admin > Assignments | Analyzes submitted text using GPTZero to detect AI-generated content, providing per-sentence analysis and downloadable reports. | +| **AI Search** | Admin Header Bar | Semantic search across the platform using AI. | +| **AI Analytics** | Admin > Reports | Generates narrative reports, identifies content gaps, and provides batch optimization suggestions. | +| **AI Tip Banner** | Student Dashboard | Context-aware training tips selected using FAISS-based recommendation. | +| **Text-to-Speech** | Listening Exams | Converts exam text to natural speech using AWS Polly (11 neural voices). | +| **Speech-to-Text** | Speaking Exams | Transcribes student speaking responses using local Whisper model. | +| **AI Avatar Videos** | Speaking Exams | Generates avatar-based video prompts for speaking exams using ELAI. | + +--- + +*End of System Features Guide* diff --git a/docs/ENCOACH_UNIFIED_SRS.md b/docs/ENCOACH_UNIFIED_SRS.md new file mode 100644 index 00000000..c6458496 --- /dev/null +++ b/docs/ENCOACH_UNIFIED_SRS.md @@ -0,0 +1,3223 @@ +# EnCoach Unified Platform -- Software Requirements Specification + +**Document Version:** 2.0 +**Date:** March 11, 2026 +**Status:** Implemented -- Staging Verified +**Supersedes:** `ielts-ui/SRS-EnCoach.md` (v2.0), `MATH_IT_ADAPTIVE_LEARNING_SRS.md` (v1.0), `ENCOACH_UNIFIED_SRS.md` (v1.0) +**Author:** EnCoach Engineering Team + +### Implementation Status + +| Artifact | Location | +|----------|----------| +| **Frontend Repository** | `https://git.albousalh.com/devops/encoach_frontend_new_v2.git` (branch: `main`) | +| **Backend Repository** | `https://git.albousalh.com/devops/encoach_backend_new_v2.git` (branch: `main`) | +| **Staging Frontend** | `http://5.189.151.117:3000` | +| **Staging Backend (Odoo 19)** | `http://5.189.151.117:8069` | +| **Frontend Stack** | React 18, TypeScript, Vite 5, shadcn/ui, TanStack Query, React Router v6 | +| **Backend Stack** | Odoo 19, Python 3.11, PostgreSQL 16, Docker Compose | +| **Frontend Pages** | 93 page components (28 root, 33 admin, 19 student, 14 teacher) | +| **Frontend Services** | 37 API service modules | +| **Frontend Types** | 29 TypeScript type definition files | +| **Frontend Query Hooks** | 21 TanStack Query hook modules | +| **Backend Custom Modules** | 27 `encoach_*` modules | +| **Backend OpenEduCat Modules** | 14 `openeducat_*` community modules | +| **Backend API Routes** | ~377 REST endpoints across 4 controller packages | + +All sections in this SRS have been implemented in both frontend and backend unless otherwise noted. The developer implemented all original SRS requirements plus additional OpenEduCat Enterprise-level features documented in Part VIII-B. + +--- + +## Table of Contents + +**Part I -- Platform Foundation** +1. [Introduction](#1-introduction) +2. [System Architecture](#2-system-architecture) +3. [User Roles and Multi-Tenancy](#3-user-roles-and-multi-tenancy) +4. [Authentication and Authorization](#4-authentication-and-authorization) +5. [Global UI Shell](#5-global-ui-shell) + +**Part II -- Universal Subject Engine** +6. [Subject Taxonomy](#6-subject-taxonomy) +7. [Diagnostic Assessment](#7-diagnostic-assessment) +8. [Proficiency Profile](#8-proficiency-profile) +9. [Learning Plan Generation](#9-learning-plan-generation) +10. [Hybrid Content Delivery](#10-hybrid-content-delivery) +11. [Progress Tracking and Mastery](#11-progress-tracking-and-mastery) + +**Part III -- LMS Module** +12. [Course Management](#12-course-management) +13. [Batch and Enrollment](#13-batch-and-enrollment) +14. [Timetable and Attendance](#14-timetable-and-attendance) +15. [Gradebook and Reports](#15-gradebook-and-reports) + +**Part IV -- Exam Engine** +16. [Exam Management](#16-exam-management) +17. [AI Content Generation](#17-ai-content-generation) +18. [Exam Delivery](#18-exam-delivery) +19. [AI Grading](#19-ai-grading) + +**Part V -- AI Services** +20. [AI Services Catalog](#20-ai-services-catalog) +21. [AI Integration in Frontend](#21-ai-integration-in-frontend) + +**Part VI -- Administration** +22. [User Management](#22-user-management) +23. [Entity Management](#23-entity-management) +24. [Classroom Management](#24-classroom-management) +25. [Assignment Management](#25-assignment-management) +26. [Permission Management](#26-permission-management) + +**Part VII -- Support and Commercial** +27. [Ticketing System](#27-ticketing-system) +28. [Subscriptions and Payments](#28-subscriptions-and-payments) +29. [Training Content](#29-training-content) + +**Part VIII -- Institutional LMS (OpenEduCat)** +30. [Academic Year and Term Management](#30-academic-year-and-term-management) +31. [Department Management](#31-department-management) +32. [Admission and Enrollment](#32-admission-and-enrollment) +33. [Subject Registration](#33-subject-registration) +34. [Institutional Exam Sessions](#34-institutional-exam-sessions) +35. [Assignment File Submissions](#35-assignment-file-submissions) + +**Part VIII-B -- OpenEduCat Enterprise Features** +36. [Student Leave Management](#36-student-leave-management) +37. [Fees Management](#37-fees-management) +38. [Lessons Management](#38-lessons-management) +39. [Gradebook and Grading Assignments](#39-gradebook-and-grading-assignments) +40. [Student Progress Tracking](#40-student-progress-tracking) +41. [Library Management](#41-library-management) +42. [Activity Management](#42-activity-management) +43. [Facility and Asset Management](#43-facility-and-asset-management) + +**Part IX -- Courseware and Content Delivery** +44. [Course Chapters](#44-course-chapters) +45. [Chapter Materials](#45-chapter-materials) +46. [AI Workbench for Course Content](#46-ai-workbench-for-course-content) + +**Part X -- Communication** +47. [Discussion Boards](#47-discussion-boards) +48. [Announcements](#48-announcements) +49. [Messaging](#49-messaging) + +**Part XI -- Notifications and FAQ** +50. [Notification Engine](#50-notification-engine) +51. [FAQ System](#51-faq-system) + +**Part XII -- Technical Specifications** +52. [Data Models](#52-data-models) +53. [REST API Specification](#53-rest-api-specification) +54. [Frontend Page Inventory](#54-frontend-page-inventory) +55. [Non-Functional Requirements](#55-non-functional-requirements) + +--- + +# Part I -- Platform Foundation + +## 1. Introduction + +### 1.1 Purpose + +This document is the definitive SRS for the EnCoach platform rebuild. It specifies all functional and non-functional requirements for a unified AI-powered education platform that serves: + +- **UTAS students** (institutional, SIS-synced, curriculum-aligned learning paths) +- **Freelance students** (self-registered, AI-generated learning plans, subscription-based) + +The platform supports multiple subjects (IELTS/English, Mathematics, Information Technology, and future subjects) through a universal adaptive learning engine. + +### 1.2 Scope + +**In scope:** +- All production features from the existing EnCoach platform (behavioural parity) +- Universal adaptive learning engine (diagnostic, proficiency, learning plans, mastery) +- Multi-subject support (IELTS, Math, IT -- extensible to any subject) +- LMS module (OpenEduCat-backed courses, batches, timetable, attendance) +- Multi-tenant operation (UTAS institutional + freelance self-service) +- AI services integration (GPT-4o, Whisper, Polly, ELAI, GPTZero, FAISS) +- New React frontend with real AI integration (replacing simulated components) +- Odoo 19 backend with REST API + +**Out of scope:** +- Mobile native applications (iOS/Android) +- Pixel-perfect recreation of old UI (new UI/UX takes precedence) +- Database internals beyond Odoo model specifications +- Hosting SLAs and legal/commercial terms + +### 1.3 Definitions + +| Term | Definition | +|------|-----------| +| **Subject** | Top-level academic discipline (IELTS/English, Mathematics, IT). Subjects are the root of the taxonomy. | +| **Domain** | Major area within a subject (e.g., Algebra, Networking, Writing). | +| **Topic** | Specific teachable unit within a domain (e.g., Linear Equations, TCP/IP). | +| **Learning Objective** | Measurable skill a student should gain from a topic. | +| **Entity** | Tenant/organization with licenses, roles, and scoped permissions. UTAS is an entity. | +| **Classroom** | User group with an admin and participants, scoped to an entity. | +| **Assignment** | Scheduled set of exams for assignees; deep link `/exam?assignment={id}`. | +| **Skill Module** | Legacy term for IELTS skill areas (reading, listening, writing, speaking, level). In the new system, skill modules are topics within the English subject. | +| **Mastery Level** | Numeric score (0-100) indicating proficiency on a topic. | +| **Learning Plan** | AI-generated, sequenced list of topics for a student to study. | +| **Resource** | Human-uploaded learning material (PDF, video, link) tagged to topics. | +| **UTAS Student** | Student enrolled through UTAS SIS sync, following institutional curriculum. | +| **Freelance Student** | Self-registered student with AI-generated learning plans, individual subscription. | + +### 1.4 Key Architectural Decisions + +| # | Decision | Rationale | +|---|----------|-----------| +| AD-1 | **Universal Subject Engine replaces hardcoded IELTS** | The exam module's `MODULE_SELECTION` becomes dynamic, driven by subject taxonomy. "Reading, Listening, Writing, Speaking" become skill types within the English subject, not hardcoded platform concepts. This allows Math, IT, and future subjects to use the same engine. | +| AD-2 | **Two student modes** | UTAS students follow curriculum + adaptive learning with SIS sync. Freelance students get fully AI-generated learning plans with no curriculum dependency. Both share the same platform. | +| AD-3 | **AI components become real** | Each of the 15 simulated AI components in the new frontend maps to specific backend AI services. No simulation in production. | +| AD-4 | **OpenEduCat as LMS backbone** | Course, batch, timetable, and attendance models come from OpenEduCat Odoo modules. A REST API bridge exposes them to the React frontend. | +| AD-5 | **Permission model extended for multi-subject** | Current hardcoded permissions (`generate_reading`, `view_writing`, etc.) are replaced with subject-parameterized permissions (`generate_exam:{subject}`, `view_exam:{subject}`). | + +--- + +## 2. System Architecture + +### 2.1 Architecture Overview + +```mermaid +graph TB + subgraph clients ["Client Layer"] + Browser["React 18 SPA
Vite + TypeScript + shadcn/ui
50+ pages"] + end + + subgraph gateway ["API Gateway"] + Nginx["Nginx
SSL Termination
Route Proxy"] + end + + subgraph backend ["Backend -- Odoo 19"] + API["REST API Controllers"] + Core["Core Modules
Users, Entities, Roles"] + Adaptive["Adaptive Engine
Taxonomy, Diagnostic,
Proficiency, Learning Plans"] + Exam["Exam Engine
Universal multi-subject"] + LMS["OpenEduCat LMS
Courses, Batches,
Timetable, Attendance"] + AImod["AI Modules
Generation, Grading,
Media, Coaching"] + Biz["Business Modules
Subscriptions, Tickets,
Registration, Assignments"] + end + + subgraph ai ["AI Services"] + GPT["OpenAI GPT-4o"] + Whisper["Whisper STT
(local)"] + Polly["AWS Polly TTS"] + ELAI_svc["ELAI Avatars"] + GPTZero_svc["GPTZero"] + FAISS_svc["FAISS + SentenceTransformers"] + end + + subgraph data ["Data"] + PG["PostgreSQL 16"] + end + + subgraph external ["External"] + SIS["UTAS SIS"] + Stripe_svc["Stripe"] + PayPal_svc["PayPal"] + Paymob_svc["Paymob"] + end + + Browser -->|HTTPS| Nginx + Nginx -->|"/app/*"| Browser + Nginx -->|"/api/*"| API + API --> Core + API --> Adaptive + API --> Exam + API --> LMS + API --> AImod + API --> Biz + AImod --> GPT + AImod --> Whisper + AImod --> Polly + AImod --> ELAI_svc + AImod --> GPTZero_svc + AImod --> FAISS_svc + Core --> PG + Adaptive --> PG + Exam --> PG + LMS --> PG + Biz --> PG + API <-->|"REST sync"| SIS + Biz --> Stripe_svc + Biz --> PayPal_svc + Biz --> Paymob_svc +``` + +### 2.2 Technology Stack + +| Layer | Technology | +|-------|-----------| +| **Frontend** | React 18, TypeScript, Vite 5, React Router v6, TanStack Query | +| **UI** | shadcn/ui (Radix primitives), Tailwind CSS 3, Recharts, Lucide icons | +| **Forms** | react-hook-form + Zod validation | +| **Backend** | Odoo 19, Python 3.11 | +| **Database** | PostgreSQL 16 | +| **LMS** | OpenEduCat (Odoo-native modules) | +| **AI** | OpenAI GPT-4o/3.5-turbo, Whisper (local base model), AWS Polly Neural, ELAI, GPTZero, FAISS + all-MiniLM-L6-v2 | +| **Deployment** | Docker Compose, Nginx reverse proxy | +| **Version Control** | Gitea | + +### 2.3 Multi-Tenant Model + +```mermaid +graph TB + subgraph tenants ["Tenant Types"] + UTAS["UTAS Entity
Institutional license
SIS-synced students
Curriculum-bound"] + Freelance["Freelance
No entity / self-entity
Self-registered
AI-generated plans
Individual subscription"] + Corp["Corporate Entities
Bulk licenses
Managed enrollment"] + end + + subgraph shared ["Shared Platform"] + SubjectEngine["Universal Subject Engine"] + ExamEngine["Exam Engine"] + AIServices["AI Services"] + LMSmod["LMS Module"] + end + + UTAS --> SubjectEngine + Freelance --> SubjectEngine + Corp --> SubjectEngine + SubjectEngine --> ExamEngine + SubjectEngine --> AIServices + SubjectEngine --> LMSmod +``` + +| Mode | Registration | Learning Plan | Content | Billing | +|------|-------------|---------------|---------|---------| +| **UTAS Student** | SIS sync or admin batch import | AI-generated, curriculum-aligned (topics from UTAS syllabus) | Manual resources from UTAS staff + AI supplementary | Institutional license | +| **Freelance Student** | Self-registration | Fully AI-generated (topic selection from global taxonomy) | AI-generated primary + curated community resources | Individual subscription (Stripe/PayPal/Paymob) | +| **Corporate Student** | Admin batch import or code-based | Teacher/admin assigned + adaptive | Entity-managed resources + AI supplementary | Corporate license | + +--- + +## 3. User Roles and Multi-Tenancy + +### 3.1 User Types + +| Type | Access | Key Capabilities | +|------|--------|-----------------| +| `student` | Student portal | Take exams, follow learning plans, view grades, attend classes, receive AI coaching | +| `teacher` | Teacher portal | Create courses, manage assignments, grade students, upload resources, view class analytics | +| `admin` | Full admin portal | Manage users/entities/classrooms, configure platform, generate exams, manage workflows | +| `corporate` | Corporate dashboard | Manage entity members, view entity statistics, bulk operations | +| `mastercorporate` | Multi-entity corporate | Cross-entity management and reporting | +| `agent` | Sales agent | Visible on landing page, sales operations | +| `developer` | Developer tools | System diagnostics, advanced configuration | + +### 3.2 Entity-Scoped Permissions + +All data access is scoped by entity membership. A user may belong to multiple entities with different roles in each. Permission checks combine **global user type** + **entity role permissions**. + +--- + +## 4. Authentication and Authorization + +> **Implementation:** `auth.service.ts` | `encoach_api/controllers/auth.py` | `Login.tsx`, `Register.tsx`, `ForgotPassword.tsx` + +### 4.1 Authentication + +| Method | Detail | +|--------|--------| +| **Primary** | Odoo JWT (HS256). Login returns access token; all API calls include `Authorization: Bearer `. | +| **Session** | Token stored in httpOnly cookie or localStorage (frontend decision). | +| **Registration** | Self-registration (freelance), batch import (institutional), code-based (corporate). | +| **Password Reset** | Email-based verification flow via `/api/reset` and `/api/reset/sendVerification`. | + +### 4.2 Authorization -- Entity Role Permissions + +77 entity-scoped permissions organized by category: + +| Category | Permissions | +|----------|-----------| +| **User Management** | `view_students`, `edit_students`, `delete_students`, `view_teachers`, `edit_teachers`, `delete_teachers`, `view_corporates`, `edit_corporates`, `delete_corporates`, `view_mastercorporates`, `edit_mastercorporates`, `delete_mastercorporates`, `create_user`, `create_user_batch` | +| **Exam Management** | `generate_{module}`, `view_{module}`, `delete_{module}` for each subject skill. Legacy: reading/listening/writing/speaking/level. New: parameterized by subject and skill via subject taxonomy. | +| **Classroom** | `view_classrooms`, `create_classroom`, `rename_classrooms`, `add_to_classroom`, `remove_from_classroom`, `delete_classroom`, `upload_classroom` | +| **Entity** | `view_entities`, `rename_entity`, `add_to_entity`, `remove_from_entity`, `delete_entity`, `view_entity_roles`, `create_entity_role`, `rename_entity_role`, `edit_role_permissions`, `assign_to_role`, `delete_entity_role`, `view_entity_statistics` | +| **Assignment** | `view_assignments`, `create_assignment`, `edit_assignment`, `delete_assignment`, `start_assignment`, `archive_assignment` | +| **Content** | `create_code`, `create_code_batch`, `view_code_list`, `delete_code`, `edit_grading_system` | +| **Reporting** | `view_statistics`, `download_statistics_report`, `view_student_performance`, `view_student_record`, `download_student_record`, `download_user_list` | +| **Financial** | `pay_entity`, `view_payment_record` | +| **Workflow** | `view_workflows`, `configure_workflows`, `edit_workflow`, `delete_workflow`, `view_approval_workflows`, `update_exam_privacy`, `view_confidential_exams`, `create_confidential_exams`, `create_public_exams` | + +### 4.3 Global Permissions + +Global permissions control page-level access independent of entity: + +| Topic | Permissions | +|-------|-----------| +| Manage Corporate | `viewCorporate`, `editCorporate`, `deleteCorporate`, `createCodeCorporate` | +| Manage Admin | `viewAdmin`, `editAdmin`, `deleteAdmin`, `createCodeAdmin` | +| Manage Student | `viewStudent`, `editStudent`, `deleteStudent`, `createCodeStudent` | +| Manage Teacher | `viewTeacher`, `editTeacher`, `deleteTeacher`, `createCodeTeacher` | +| Manage Exams | `createReadingExam`, `createListeningExam`, `createWritingExam`, `createSpeakingExam`, `createLevelExam` -- **extended per subject** | +| View Pages | `viewExams`, `viewExercises`, `viewRecords`, `viewStats`, `viewTickets`, `viewPaymentRecords` | +| Manage Groups | `viewGroup`, `editGroup`, `deleteGroup`, `createGroup` | +| Manage Codes | `viewCodes`, `deleteCodes`, `createCodes` | +| Super | `all` | + +### 4.4 Permission Extension for Multi-Subject (AD-5) + +The current permission model is IELTS-hardcoded (`generate_reading`, `createWritingExam`, etc.). For multi-subject support: + +**Strategy:** Add subject-parameterized permissions while maintaining backward compatibility. + +| Current (IELTS-only) | New (Universal) | Mapping | +|----------------------|----------------|---------| +| `generate_reading` | `generate_exam:english:reading` | Existing English exams auto-map | +| `generate_writing` | `generate_exam:english:writing` | Same | +| (new) | `generate_exam:math:algebra` | New subject permissions | +| (new) | `generate_exam:it:networking` | New subject permissions | +| (new) | `manage_taxonomy:{subject}` | Taxonomy administration per subject | +| (new) | `manage_resources:{subject}` | Resource upload per subject | +| (new) | `view_adaptive:{subject}` | View adaptive learning data per subject | + +--- + +## 5. Global UI Shell + +### 5.1 Navbar + +| ID | Requirement | Source | +|----|-------------|--------| +| FR-GNAV-01 | Brand/logo links to role-appropriate dashboard | Production | +| FR-GNAV-02 | Student: subject progress indicators (mastery % per enrolled subject) | New (replaces IELTS-only skill indicators) | +| FR-GNAV-03 | Help button opens ticket submission with page context | Production | +| FR-GNAV-04 | Subscription/expiry indicator; link to payment when applicable | Production | +| FR-GNAV-05 | Profile link to `/profile` | Production | +| FR-GNAV-06 | Mobile-responsive menu | Production | +| FR-GNAV-07 | AI Search Bar (global) -- keyword search with AI-powered suggestions, route to relevant pages | New frontend | +| FR-GNAV-08 | AI Assistant Drawer -- chat-style AI help accessible from any page | New frontend | + +### 5.2 Sidebar Navigation + +| ID | Requirement | +|----|-------------| +| FR-SIDE-01 | Entries appear only when permitted (user type + entity permissions) | +| FR-SIDE-02 | Sidebar minimize preference persisted locally | +| FR-SIDE-03 | Logout ends session and clears state | +| FR-SIDE-04 | Ticket badge shows assigned count | + +**Student sidebar:** Dashboard, Subjects, Courses, Subject Registration, Assignments, Grades, Attendance, Timetable, Discussions, Messages, Announcements, Journey, Profile + +**Teacher sidebar:** Dashboard, Courses, Assignments, Attendance, Students, Timetable, Discussions, Announcements, Profile + +**Admin sidebar (grouped):** + +| Group | Items | +|-------|-------| +| **LMS** | Dashboard, Courses, Students, Teachers, Batches, Timetable, Reports, Settings | +| **Platform** | Platform Dashboard | +| **Institutional** | Academic Years, Departments, Admissions, Exam Sessions, Marksheets | +| **Academic** | Assignments, Exams List, Exam Structures, Rubrics, Generation, Approval Workflows | +| **Management** | Users, Entities, Classrooms, Taxonomy Manager, Resource Manager | +| **Reports** | Student Performance, Stats Corporate, Record | +| **Training** | Vocabulary, Grammar | +| **Support** | Payment Record, Tickets, Settings | + +### 5.3 Breadcrumbs + +Inner pages show: Home > Section > Nested segments (e.g., Assignments > Creator, Training > Vocabulary). + +--- + +# Part II -- Universal Subject Engine + +## 6. Subject Taxonomy + +> **Implementation:** `taxonomy.service.ts` | `encoach_adaptive_api/controllers/taxonomy.py` | `AdminTaxonomy.tsx` + +### 6.1 Hierarchy + +``` +Subject (e.g., Mathematics) +└── Domain (e.g., Algebra) + └── Topic (e.g., Linear Equations) + └── Learning Objective (e.g., "Solve 2-variable systems") +``` + +Topics form a directed acyclic graph via prerequisite relationships. A student cannot begin a topic until all prerequisites reach Proficient (mastery >= 60%). + +### 6.2 IELTS / English Taxonomy + +The existing IELTS skills map into the universal taxonomy: + +``` +English / IELTS +├── Reading +│ ├── Skimming and Scanning (prerequisites: none) +│ ├── Detail Comprehension (prerequisites: Skimming) +│ ├── Inference and Deduction (prerequisites: Detail Comprehension) +│ └── Academic Reading (prerequisites: Inference) +├── Listening +│ ├── Section 1-2: Social/Everyday (prerequisites: none) +│ ├── Section 3-4: Academic (prerequisites: Section 1-2) +│ └── Note/Summary Completion (prerequisites: Section 1-2) +├── Writing +│ ├── Task 1 General: Letter (prerequisites: none) +│ ├── Task 1 Academic: Data Description (prerequisites: none) +│ └── Task 2: Essay (prerequisites: Task 1 General or Task 1 Academic) +├── Speaking +│ ├── Part 1: Introduction (prerequisites: none) +│ ├── Part 2: Long Turn (prerequisites: Part 1) +│ └── Part 3: Discussion (prerequisites: Part 2) +└── General English + ├── Grammar Foundations (prerequisites: none) + ├── Vocabulary Building (prerequisites: none) + └── Pronunciation (prerequisites: none) +``` + +### 6.3 Mathematics Taxonomy + +``` +Mathematics +├── Arithmetic +│ ├── Number Operations (prerequisites: none) +│ ├── Fractions and Decimals (prerequisites: Number Operations) +│ └── Ratios and Proportions (prerequisites: Fractions) +├── Algebra +│ ├── Algebraic Expressions (prerequisites: Number Operations) +│ ├── Linear Equations (prerequisites: Algebraic Expressions) +│ ├── Quadratic Equations (prerequisites: Linear Equations) +│ └── Polynomials (prerequisites: Quadratic Equations) +├── Geometry +│ ├── Basic Shapes (prerequisites: Number Operations) +│ ├── Angles and Triangles (prerequisites: Basic Shapes) +│ ├── Coordinate Geometry (prerequisites: Linear Equations, Basic Shapes) +│ └── Trigonometry (prerequisites: Angles, Coordinate Geometry) +├── Statistics and Probability +│ ├── Data Representation (prerequisites: Number Operations) +│ ├── Central Tendency (prerequisites: Data Representation) +│ └── Basic Probability (prerequisites: Fractions) +└── Calculus + ├── Limits (prerequisites: Polynomials, Coordinate Geometry) + ├── Derivatives (prerequisites: Limits) + └── Integrals (prerequisites: Derivatives) +``` + +### 6.4 Information Technology Taxonomy + +``` +Information Technology +├── Computer Fundamentals +│ ├── Hardware Components (prerequisites: none) +│ ├── Operating Systems (prerequisites: Hardware) +│ └── Number Systems (prerequisites: none) +├── Networking +│ ├── Network Basics (prerequisites: Hardware) +│ ├── TCP/IP Model (prerequisites: Network Basics) +│ ├── IP Addressing (prerequisites: TCP/IP, Number Systems) +│ └── Network Security (prerequisites: IP Addressing) +├── Databases +│ ├── Database Concepts (prerequisites: Operating Systems) +│ ├── SQL Fundamentals (prerequisites: Database Concepts) +│ ├── Database Design (prerequisites: SQL Fundamentals) +│ └── Advanced SQL (prerequisites: Database Design) +├── Programming +│ ├── Programming Logic (prerequisites: none) +│ ├── Python Basics (prerequisites: Programming Logic) +│ ├── Data Structures (prerequisites: Python Basics) +│ └── Object-Oriented Programming (prerequisites: Data Structures) +└── Cybersecurity + ├── Security Fundamentals (prerequisites: Network Security) + └── Cryptography Basics (prerequisites: Security Fundamentals, Number Systems) +``` + +### 6.5 Taxonomy Management + +| Action | Actor | API | +|--------|-------|-----| +| Create/edit subjects | Admin | `POST/PATCH /api/subjects` | +| Create/edit domains | Admin / Staff | `POST/PATCH /api/domains` | +| Create/edit topics with prerequisites | Staff | `POST/PATCH /api/topics` | +| Create/edit learning objectives | Staff | Nested in topic API | +| Bulk import taxonomy (JSON/CSV) | Admin | `POST /api/subjects/{id}/taxonomy/import` | +| AI-suggest sub-topics for a domain | Staff | `POST /api/domains/{id}/ai-suggest` | + +--- + +## 7. Diagnostic Assessment + +> **Implementation:** `adaptive.service.ts` | `encoach_adaptive_api/controllers/diagnostic.py` | `StudentDiagnostic.tsx` + +### 7.1 Purpose + +When a student begins a new subject, a diagnostic assessment determines their per-topic proficiency. This is the input for learning plan generation. For English, this replaces/extends the existing Level Test. + +### 7.2 Adaptive Algorithm + +The diagnostic uses Computer Adaptive Testing: starts at medium difficulty, adjusts up on correct answers, down on incorrect. Cycles through domains round-robin. + +| Parameter | Default | Configurable | +|-----------|---------|-------------| +| `questions_per_domain` | 4 | Yes (per subject) | +| `total_question_cap` | 25 | Yes | +| `time_limit_minutes` | 45 | Yes | +| `starting_difficulty` | `medium` | Yes | +| `mastery_per_correct` | +25 | Yes | +| `mastery_per_incorrect` | -10 | Yes | + +### 7.3 Question Types per Subject + +| Subject | Question Types | +|---------|---------------| +| **English** | Multiple choice, fill blanks, short answer, essay (writing), oral (speaking) | +| **Math** | Multiple choice, numerical (tolerance-graded), short answer, fill blanks, worked problem (multi-step) | +| **IT** | Multiple choice, true/false, short answer, code completion, scenario-based | + +### 7.4 Integration with Existing Exam Model + +Diagnostics reuse `encoach.exam` with `is_diagnostic = True` and a new `subject_id` field. `MODULE_SELECTION` extended with `math_diagnostic`, `it_diagnostic`. The existing `level` module maps to `english_diagnostic`. + +--- + +## 8. Proficiency Profile + +> **Implementation:** `adaptive.service.ts` | `encoach_adaptive_api/controllers/proficiency.py` | `StudentProficiency.tsx` + +### 8.1 Mastery Levels + +| Level | Score Range | Color | +|-------|-----------|-------| +| Not Started | 0-19% | Grey | +| Beginner | 20-39% | Red | +| Developing | 40-59% | Orange | +| Proficient | 60-79% | Yellow | +| Mastered | 80-100% | Green | + +### 8.2 Profile Updates + +| Trigger | Update Logic | +|---------|-------------| +| Diagnostic | Initial scores set per topic | +| Practice exercises | +5 correct, -2 incorrect | +| Mastery quiz | Pass (>= threshold): topic mastered. Fail: weighted average recalculation. | +| Time decay | -5% per week of inactivity after 30 days, floor at last quiz score minus 20% | + +--- + +## 9. Learning Plan Generation + +> **Implementation:** `adaptive.service.ts` | `encoach_adaptive_api/controllers/learning_plan.py` | `StudentLearningPlan.tsx` + +### 9.1 Two Modes + +| Mode | UTAS Student | Freelance Student | +|------|-------------|-------------------| +| **Scope** | Topics from UTAS curriculum for enrolled courses | All topics in selected subject | +| **Constraints** | Semester dates, course schedule | Self-set target date or open-ended | +| **Content** | UTAS-uploaded resources + AI supplementary | AI-generated primary + community resources | +| **Prerequisite enforcement** | Yes, with teacher override | Yes, no override | +| **Plan visibility** | Student + assigned teacher + admin | Student only | + +### 9.2 Algorithm + +1. **Topological sort** -- order topics respecting prerequisites +2. **Filter mastered** -- exclude topics with mastery >= threshold +3. **Prioritize** -- lowest mastery first, balanced across domains +4. **Estimate duration** -- based on topic complexity and current mastery +5. **AI refinement** -- GPT-4o generates motivational summary and specific advice + +### 9.3 Plan Adjustments + +| Trigger | Action | +|---------|--------| +| Faster mastery than estimated | Unlock next topic early | +| 3+ failed mastery quizzes | Additional resources, AI coaching intensified | +| Teacher override (UTAS) | Reorder, add/remove topics | +| 7+ days inactive | Notification; 14+ days pauses plan | + +--- + +## 10. Hybrid Content Delivery + +> **Implementation:** `adaptive.service.ts`, `resources.service.ts`, `coaching.service.ts` | `encoach_adaptive_api/controllers/content.py`, `encoach_resources/controllers/resources_rest.py` | `StudentTopic.tsx` + +### 10.1 Content Resolution Order + +1. **Human-uploaded resources** tagged to the topic (PDFs, videos, links) +2. **AI-generated content** if no human resources exist (explanations, worked examples, summaries) +3. **Content gap flag** if neither is available -- notifies admin + +### 10.2 Resource Types + +| Type | Format | Upload | +|------|--------|--------| +| PDF | `.pdf` | File upload | +| Video | URL (YouTube, Vimeo) or file upload | URL or multipart | +| External Link | Any URL | URL field | +| Document | `.docx`, `.pptx` | File upload | +| Interactive | Embedded HTML | URL field | + +### 10.3 AI Coaching + +| Action | Backend Service | Trigger | +|--------|----------------|---------| +| Answer explanation | GPT-4o | After each practice question | +| Hint | GPT-4o | Student requests during practice | +| Study suggestion | GPT-4o | After completing a topic section | +| Weakness analysis | GPT-4o | After failing mastery quiz | +| Formula reference (Math) | Static + GPT-4o | On demand | +| Motivational nudge | GPT-4o | 3+ days inactive | + +--- + +## 11. Progress Tracking and Mastery + +> **Implementation:** `adaptive.service.ts`, `analytics.service.ts` | `encoach_adaptive_api/controllers/content.py`, `encoach_api/controllers/ai_analytics.py` | `StudentJourney.tsx`, `AdminAdaptiveAnalytics.tsx` + +### 11.1 Mastery Quiz + +| Parameter | Value | +|-----------|-------| +| Questions | 5-10 (configurable per subject) | +| Time limit | 15 minutes (configurable) | +| Pass threshold | 80% (configurable per subject) | +| Attempts | Unlimited, new questions each time | +| Cooldown | 1 hour between attempts | +| On pass | Topic completed, next unlocked | +| On fail | Mastery recalculated, AI coaching triggered | + +### 11.2 Spaced Repetition + +| Days Since Mastery | Review | +|-------------------|--------| +| 7 | 3 quick-recall questions | +| 30 | 5 questions at original difficulty | +| 90 | Full mastery quiz equivalent | + +### 11.3 Analytics + +**Student:** Overall mastery %, domain radar chart, plan progress, study streak, upcoming reviews. + +**Teacher:** Class mastery heatmap, at-risk students, content gap report, time per topic vs estimate. + +**Admin:** Subject-level stats (enrollments, completion rates, avg mastery), AI usage metrics, resource utilization. + +--- + +# Part III -- LMS Module + +## 12. Course Management + +> **Implementation:** `lms.service.ts` | `encoach_lms_api/controllers/courses.py` | `StudentCourses.tsx`, `TeacherCourses.tsx`, `AdminCourses.tsx` + +### 12.1 Overview + +Courses are managed through OpenEduCat models exposed via REST API. The frontend provides student, teacher, and admin course views. + +### 12.2 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-CRS-01 | List enrolled courses with progress | `/student/courses` | Student | +| FR-CRS-02 | View course detail with modules and lessons | `/student/courses/:id` | Student | +| FR-CRS-03 | List managed courses | `/teacher/courses` | Teacher | +| FR-CRS-04 | Create new course with modules and lessons | `/teacher/courses/new` | Teacher | +| FR-CRS-05 | Edit existing course | `/teacher/courses/:id/edit` | Teacher | +| FR-CRS-06 | Admin course management (all courses, all entities) | `/admin/courses` | Admin | + +### 12.3 Course Data Model + +| Field | Type | Description | +|-------|------|-------------| +| title | String | Course title | +| code | String | Course code (e.g., "MATH101") | +| subject_id | Reference | Link to subject taxonomy | +| instructor_id | Reference | Assigned teacher | +| description | Text | Course description | +| level | Selection | Beginner, Intermediate, Advanced | +| modules | One2many | Course modules (units) | +| max_capacity | Integer | Enrollment limit | +| start_date / end_date | Date | Course period | +| status | Selection | draft, active, archived | + +--- + +## 13. Batch and Enrollment + +> **Implementation:** `lms.service.ts` | `encoach_lms_api/controllers/batches.py` | `AdminBatches.tsx` + +| ID | Requirement | Route | +|----|-------------|-------| +| FR-BATCH-01 | List batches with student counts | `/admin/batches` | +| FR-BATCH-02 | View batch detail with enrolled students | `/admin/batches/:id` | +| FR-BATCH-03 | Create batch, assign students and courses | Admin | +| FR-BATCH-04 | Enrollment: student self-enrollment (freelance) or admin assignment (UTAS) | API | + +--- + +## 14. Timetable and Attendance + +> **Implementation:** `lms.service.ts` | `encoach_lms_api/controllers/timetable.py`, `encoach_lms_api/controllers/attendance.py` | `StudentTimetable.tsx`, `TeacherTimetable.tsx`, `AdminTimetable.tsx`, `StudentAttendance.tsx`, `TeacherAttendance.tsx` + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-TT-01 | View personal timetable | `/student/timetable` | Student | +| FR-TT-02 | View teaching timetable | `/teacher/timetable` | Teacher | +| FR-TT-03 | Manage timetable (create, edit sessions) | `/admin/timetable` | Admin | +| FR-ATT-01 | View personal attendance | `/student/attendance` | Student | +| FR-ATT-02 | Record attendance for class | `/teacher/attendance` | Teacher | + +--- + +## 15. Gradebook and Reports + +> **Implementation:** `lms.service.ts`, `analytics.service.ts` | `encoach_lms_api/controllers/grades.py`, `encoach_api/controllers/ai_analytics.py` | `StudentGrades.tsx`, `AdminReports.tsx` + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-GRD-01 | View personal grades across courses | `/student/grades` | Student | +| FR-GRD-02 | Grade student submissions | `/teacher/assignments/:id` | Teacher | +| FR-RPT-01 | Academic reports with charts | `/admin/reports` | Admin | +| FR-RPT-02 | AI-generated report narratives | `/admin/reports` (AiReportNarrative) | Admin | + +--- + +# Part IV -- Exam Engine + +## 16. Exam Management + +> **Implementation:** `exams.service.ts` | `encoach_api/controllers/exam.py` | `AdminExamsList.tsx`, `AdminExamStructures.tsx`, `AdminRubrics.tsx`, `Exam.tsx` + +### 16.1 Exam CRUD (Production Parity) + +| ID | Requirement | Source | +|----|-------------|--------| +| FR-EX-01 | Filter exams by module (extended: by subject and skill) | Production | +| FR-EX-02 | Load exam by Exam ID | Production | +| FR-EX-03 | Text search | Production | +| FR-EX-04 | Pagination and page size | Production | +| FR-EX-05 | Columns: title, creator, module, rubrics, difficulty, exercises, timer, access, created at | Production | +| FR-EX-06 | Row actions: set public/private, edit, load, delete | Production | +| FR-EX-07 | **NEW:** Subject filter (English, Math, IT) alongside module filter | New | +| FR-EX-08 | **NEW:** Exercise vs Exam differentiation -- `is_exercise` flag; exercises are self-paced practice (no journey tracking), exams are official graded assessments | Client | +| FR-EX-09 | **NEW:** `is_official` flag on exams -- official exams track to student journey and support special access modes | Client | +| FR-EX-10 | **NEW:** Official exam access modes: (1) unique shareable link, (2) landing page access, (3) separate login screen | Client | +| FR-EX-11 | **NEW:** Exam activation control -- teacher sets start date, end date, activation status | Client | +| FR-EX-12 | **NEW:** Different exam for each student option (AI generates unique variants per student) | Client | +| FR-EX-13 | **NEW:** Configurable reminder frequency -- number of reminders, notification via email and system notification | Client | +| FR-EX-14 | **NEW:** Exam suspend/revoke actions | Client | +| FR-EX-15 | **NEW:** Student inquiry and extension requests on exams | Client | + +### 16.2 Official Exam Access (NEW) + +| Access Mode | Description | Route | +|-------------|-------------|-------| +| **Link Access** | Teacher generates a unique URL; students access exam via the link without full platform login | `/exam/access/{token}` | +| **Landing Page** | Exam appears on the public landing page; students authenticate with exam code + credentials | `/exam/official/{code}` | +| **Separate Login** | Dedicated login screen for the exam only; no access to other platform features | `/exam/login/{examId}` | + +### 16.4 Rubrics (Production Parity) + +| ID | Requirement | +|----|-------------| +| FR-RUB-01-05 | Search, pagination, create rubric, filter dropdown, metadata and edit | +| FR-RG-01-05 | Rubric groups: search, pagination, create, filter, edit/delete | + +### 16.5 Exam Structures (Production Parity) + +| ID | Requirement | +|----|-------------| +| FR-ES-01 | Entity selector | +| FR-ES-02 | Text search | +| FR-ES-03 | Create structure (extended: per subject) | +| FR-ES-04 | Delete structure(s) | +| FR-ES-05 | Pagination | + +--- + +## 17. AI Content Generation + +> **Implementation:** `generation.service.ts` | `encoach_api/controllers/generation.py` | `AdminGeneration.tsx` + +### 17.1 Generation per Subject + +| Subject | AI Generates | Prompt Model | +|---------|-------------|-------------| +| **English** | Reading passages, listening scripts, writing tasks, speaking questions, level test exercises | GPT-4o (temp 0.7 for generation) | +| **Math** | Questions per topic (MCQ, numerical, word problems, worked problems) | GPT-4o with LaTeX output | +| **IT** | Questions per topic (MCQ, true/false, code completion, scenarios) | GPT-4o with code block output | + +### 17.2 Generation Workflow + +| ID | Requirement | Source | +|----|-------------|--------| +| FR-GEN-01 | Select title, label, entity, subject, and skill/module | Production (extended) | +| FR-GEN-02 | AI generates exam content via GPT-4o | Production | +| FR-GEN-03 | **NEW:** AI Creation Assistant -- modal flow for "Create with AI" for courses, exams, rubrics, assignments | New frontend (AiCreationAssistant) | +| FR-GEN-04 | **NEW:** AI Generator Modal -- configurable generation parameters | New frontend (AiGeneratorModal) | + +--- + +## 18. Exam Delivery + +> **Implementation:** `exams.service.ts`, `media.service.ts` | `encoach_api/controllers/exam.py`, `encoach_api/controllers/generation.py` | `Exam.tsx`, `OfficialExam.tsx` + +### 18.1 Delivery Modes + +| Mode | Route | Chrome | +|------|-------|--------| +| Practice | `/exam` | Full UI with navigation | +| Assignment | `/exam?assignment={id}` | Reduced chrome | +| Official | `/official-exam` | Minimal chrome, strict timer | +| Diagnostic | `/student/diagnostic/:subjectId` | Adaptive, one question at a time | +| Mastery Quiz | `/student/mastery-quiz/:topicId` | Standard quiz, fresh questions | + +### 18.2 Media Integration + +| Media | Service | Usage | +|-------|---------|-------| +| Listening audio | AWS Polly TTS | English listening sections (11 neural voices) | +| Speaking video | ELAI avatars | English speaking prompts (7 avatars) | +| Speaking transcription | Whisper STT | Student audio transcription for grading | + +--- + +## 19. AI Grading + +> **Implementation:** `evaluations.service.ts`, `plagiarism.service.ts` | `encoach_api/controllers/generation.py`, `encoach_lms_api/controllers/plagiarism.py` | `AdminApprovalWorkflows.tsx` + +### 19.1 Grading per Subject + +| Subject | Grading Type | Method | +|---------|-------------|--------| +| English Writing | Rubric-based (IELTS band scoring) | GPT-4o (temp 0.1) evaluates Task Achievement, Coherence, Lexical Resource, Grammar | +| English Speaking | Rubric-based (IELTS band scoring) | Whisper transcription + GPT-4o grading | +| English Short Answer | Passage-based | GPT-4o evaluates against correct answers | +| Math MCQ | Exact match | Direct comparison | +| Math Numerical | Tolerance-based | `abs(student - correct) <= tolerance` | +| Math Worked Problem | Step evaluation | GPT-4o evaluates methodology and answer | +| IT MCQ / True-False | Exact match | Direct comparison | +| IT Code Completion | AI evaluation | GPT-4o evaluates correctness, approach, quality | +| IT Scenario | AI evaluation | GPT-4o evaluates against rubric | +| All Writing | AI detection | GPTZero per-sentence analysis | + +### 19.2 Plagiarism Detection (NEW -- Implemented) + +> **Implementation:** `plagiarism.service.ts` | `encoach_lms_api/controllers/plagiarism.py` + +| ID | Requirement | Source | +|----|-------------|--------| +| FR-PLAG-01 | Enable/disable plagiarism check per assignment or exam | Client | +| FR-PLAG-02 | Automatic GPTZero analysis on submission | Client | +| FR-PLAG-03 | Downloadable plagiarism report (PDF) per submission | Client | +| FR-PLAG-04 | Configurable number of allowed submissions with plagiarism check | Client | +| FR-PLAG-05 | Teacher views plagiarism score and per-sentence analysis in grading interface | Client | +| FR-PLAG-06 | Aggregate plagiarism overview for assignment (flagged submissions count) | Client | + +**API Endpoints:** + +| Method | Path | Description | +|--------|------|-------------| +| `POST` | `/api/plagiarism/check` | Run plagiarism check on text/submission | +| `GET` | `/api/plagiarism/report/{submissionId}` | Get plagiarism report | +| `GET` | `/api/plagiarism/report/{submissionId}/download` | Download report as PDF | + +### 19.3 Approval Workflows (Enhanced) + +| ID | Requirement | Source | +|----|-------------|--------| +| FR-AWF-01 | List/filter workflows | Production | +| FR-AWF-02 | Create templates / add workflow | Production | +| FR-AWF-03 | **NEW:** AI Grading Assistant on workflow page | New frontend | +| FR-AWF-04 | **NEW:** Configurable approval stages with number of days per stage (shown as calendar) | Client | +| FR-AWF-05 | **NEW:** Auto-escalation -- if time passes, automatically move to next authority with highlighted reason | Client | +| FR-AWF-06 | **NEW:** Bypass option -- terminate approval flow with mandatory justification sent to final authority | Client | +| FR-AWF-07 | **NEW:** Comments saved through the approval process | Client | +| FR-AWF-08 | **NEW:** Status view of approval progress (first reviewer, rejected, final reviewer, etc.) | Client | +| FR-AWF-09 | **NEW:** Final authority can choose who to pass back the exam to | Client | +| FR-AWF-10 | **NEW:** Configurable email notifications per approval stage | Client | +| FR-AWF-11 | **NEW:** Approval applies to both exams and course materials | Client | + +**Approval Stage Model:** + +| Field | Type | Description | +|-------|------|-------------| +| `workflow_id` | Many2one | Parent workflow | +| `sequence` | Integer | Stage order | +| `approver_id` | Many2one | Approver user | +| `max_days` | Integer | Maximum days before auto-escalation | +| `notification_email` | Char | Email for notifications | +| `status` | Selection | `pending`, `approved`, `rejected`, `escalated`, `bypassed` | +| `comment` | Text | Reviewer comment | +| `acted_at` | Datetime | When action was taken | + +--- + +# Part V -- AI Services + +## 20. AI Services Catalog + +> **Implementation:** `coaching.service.ts`, `analytics.service.ts`, `generation.service.ts`, `evaluations.service.ts`, `media.service.ts` | `encoach_ai/`, `encoach_ai_generation/`, `encoach_ai_grading/`, `encoach_ai_media/`, `encoach_adaptive_ai/` + +| Service | Model | Config | Usage | +|---------|-------|--------|-------| +| **OpenAI GPT-4o** | gpt-4o (primary), gpt-3.5-turbo (secondary) | Temp: 0.1 grading, 0.7 generation, 0.2 summaries. Max tokens: 4,097. JSON format. | Exam generation, grading, evaluation, training tips, learning plans, coaching, content generation | +| **Whisper** | base (local, ~1GB) | 4 instances, round-robin, 16kHz mono, 30s chunks | Speaking transcription, audio-to-text | +| **AWS Polly** | Neural engine | 11 voices, MP3, 3,000 char chunks | Listening exam audio | +| **ELAI** | 7 avatars | ElevenLabs + Azure voices, fade_in animation | Speaking exam video, virtual tutoring | +| **GPTZero** | v2/predict/text | Per-sentence analysis, confidence scoring | Writing AI detection | +| **FAISS** | IndexFlatL2 + all-MiniLM-L6-v2 | Top-5, per-subject indices | Training tips, content recommendations | + +--- + +## 21. AI Integration in Frontend + +Each simulated AI component in the new frontend maps to a real backend service: + +| Frontend Component | Mock Behavior | Real Backend Integration | +|-------------------|--------------|--------------------------| +| `AiAssistantDrawer` | Canned responses via `mockResponses` map | GPT-4o conversational API. Context: current page, student profile, recent activity. Endpoint: `POST /api/coach/chat` | +| `AiSearchBar` | Keyword-to-route mapping | GPT-4o semantic search + FAISS. Returns relevant content, pages, and actions. Endpoint: `POST /api/ai/search` | +| `AiCreationAssistant` | Simulated creation flows | GPT-4o generates course outlines, exam content, rubrics, assignments based on type parameter. Endpoints: existing `/api/exam/*/generate` + new `/api/courses/ai-generate` | +| `AiGeneratorModal` | Simulated with setTimeout | Real generation call to GPT-4o with progress streaming. Endpoint: existing generation endpoints | +| `AiGradingAssistant` | Fixed suggested marks | Real grading via `POST /api/evaluate/writing` or `/api/evaluate/speaking` or `/api/grading/multiple`. Returns scores + feedback | +| `AiWritingHelper` | `useAiSimulation` delay | GPT-4o writing assistance. Endpoint: `POST /api/coach/writing-help` | +| `AiGradeExplainer` | Static explanation | GPT-4o explains grade breakdown. Endpoint: `POST /api/coach/explain` | +| `AiStudyCoach` | Rotating static tips | Real adaptive engine: proficiency profile + FAISS tips + GPT-4o recommendations. Endpoint: `POST /api/coach/suggest` | +| `AiInsightsPanel` | Static insight cards | GPT-4o analysis of student/class data. Endpoint: `POST /api/ai/insights` | +| `AiTipBanner` | Static tips | Context-aware tips from FAISS + GPT-4o. Endpoint: `GET /api/coach/tip?context={page}` | +| `AiAlertBanner` | Static alerts | Rule-based alerts (attendance, grades) + GPT-4o severity assessment. Endpoint: `GET /api/ai/alerts` | +| `AiReportNarrative` | Static narrative | GPT-4o generates report narrative from analytics data. Endpoint: `POST /api/ai/report-narrative` | +| `AiRiskBadge` | Heuristic from mock data | Risk calculation from attendance + grades + engagement. Endpoint: included in student profile API | +| `AiBatchOptimizer` | Static suggestions | GPT-4o analyzes batch composition and suggests optimizations. Endpoint: `POST /api/ai/batch-optimize` | +| `useAiSimulation` | setTimeout + canned response | Replaced by real TanStack Query mutations to backend APIs | + +--- + +# Part VI -- Administration + +## 22. User Management (Production Parity) + +> **Implementation:** `users.service.ts` | `encoach_api/controllers/users.py` | `AdminUsers.tsx` + +| ID | Requirement | Route | +|----|-------------|-------| +| FR-USR-01 | Filter by entity | `/users?type=student\|teacher\|corporate\|mastercorporate` | +| FR-USR-02 | Text search (name/email) | Same | +| FR-USR-03 | Download/export | Same | +| FR-USR-04 | Pagination and page size | Same | +| FR-USR-05 | Type-specific columns (name, email, type, entities, classrooms, student ID, verified) | Same | +| FR-USR-06 | **NEW:** Subject enrollment status per student | New | + +--- + +## 23. Entity Management (Production Parity) + +> **Implementation:** `entities.service.ts` | `encoach_api/controllers/entities.py` | `AdminEntities.tsx` + +| ID | Requirement | +|----|-------------| +| FR-ENT-01 | Search and pagination | +| FR-ENT-02 | Create entity (label, licenses/capacity, member selection) | +| FR-ENT-03 | Cards: usage/capacity, role counts | +| FR-ENT-04 | Role and permission management per entity | + +--- + +## 24. Classroom Management (Production Parity) + +> **Implementation:** `classrooms.service.ts` | `encoach_api/controllers/classroom.py` | `AdminClassrooms.tsx` + +| ID | Requirement | +|----|-------------| +| FR-CL-01 | Entity filter and search | +| FR-CL-02 | Cards: name, admin, entity, participant count | +| FR-CL-03 | Create classroom | +| FR-CL-04 | Transfer students across classrooms | +| FR-CL-05 | Delete / bulk delete | + +--- + +## 25. Assignment Management (Production Parity) + +> **Implementation:** `assignments.service.ts` | `encoach_api/controllers/assignment.py` | `AdminAssignments.tsx`, `StudentAssignments.tsx`, `TeacherAssignments.tsx` + +| ID | Requirement | +|----|-------------| +| FR-ASG-01 | Tabs: Active, Planned, Past, Start Expired, Archived with counts | +| FR-ASG-02 | Create assignment (entity, dates, classrooms, assignees, exams) | +| FR-ASG-03 | Search and pagination (`state`, `page`, `size`) | +| FR-ASG-04 | Breadcrumb navigation | +| FR-ASG-05 | Assignment execution via `/exam?assignment={id}` | +| FR-ASG-06 | **NEW:** Subject-scoped assignments (assign Math exams, IT exams, not just IELTS) | +| FR-ASG-07 | **NEW:** Late submission handling -- configurable late submission date/time with penalty structure | Client | +| FR-ASG-08 | **NEW:** Extension requests -- students can request deadline extensions through the platform | Client | +| FR-ASG-09 | **NEW:** Submission tracking -- status flow (start date, extension granted, submitted, in review, graded) | Client | +| FR-ASG-10 | **NEW:** Configurable number of allowed submissions per assignment | Client | +| FR-ASG-11 | **NEW:** Revision history -- track all submission versions per student | Client | +| FR-ASG-12 | **NEW:** Reminder notifications -- configurable frequency, sent via email and system notification | Client | + +### 25.2 Late Submission Policy + +| Field | Type | Description | +|-------|------|-------------| +| `late_deadline` | Datetime | Final late submission cutoff | +| `penalty_type` | Selection | `none`, `percentage`, `fixed_deduction` | +| `penalty_value` | Float | Penalty amount (e.g., 10 = 10% or 10 points) | +| `max_submissions` | Integer | Maximum allowed submissions (0 = unlimited) | +| `allow_extensions` | Boolean | Whether students can request extensions | + +### 25.3 Extension Request + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Requesting student | +| `assignment_id` | Many2one | Target assignment | +| `reason` | Text | Justification | +| `requested_date` | Datetime | Requested new deadline | +| `status` | Selection | `pending`, `approved`, `rejected` | +| `approved_by` | Many2one | Approving teacher | +| `response_note` | Text | Teacher response | + +--- + +## 26. Permission Management (Production Parity + Extension) + +> **Implementation:** `entities.service.ts` (roles/permissions) | `encoach_api/controllers/roles.py` | `RolesPermissions.tsx`, `AuthorityMatrix.tsx`, `UserRoles.tsx` + +| ID | Requirement | +|----|-------------| +| FR-PERM-01 | Navigate permission types at `/permissions` | +| FR-PERM-02 | View/edit permission details at `/permissions/:id` | +| FR-PERM-03 | **NEW:** Subject-parameterized permissions in UI (select subject, then skill permissions) | + +### 26.2 Roles and Permissions CRUD (NEW -- Implemented) + +The developer implemented a complete roles and permissions CRUD system beyond the original entity-scoped model. + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-ROLE-01 | List all roles with permission counts | `/admin/roles-permissions` | Admin | +| FR-ROLE-02 | Create role with name and description | `/admin/roles-permissions` | Admin | +| FR-ROLE-03 | Update role details | `/admin/roles-permissions` | Admin | +| FR-ROLE-04 | Delete role | `/admin/roles-permissions` | Admin | +| FR-ROLE-05 | Update role permissions (assign/remove permissions) | `/admin/roles-permissions` | Admin | +| FR-ROLE-06 | List all permissions | `/admin/roles-permissions` | Admin | +| FR-ROLE-07 | Create custom permission | `/admin/roles-permissions` | Admin | +| FR-ROLE-08 | Delete permission | `/admin/roles-permissions` | Admin | + +**API Endpoints:** + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/roles` | List all roles | +| `POST` | `/api/roles` | Create role | +| `GET` | `/api/roles/{id}` | Get role detail | +| `PATCH` | `/api/roles/{id}` | Update role | +| `DELETE` | `/api/roles/{id}` | Delete role | +| `PATCH` | `/api/roles/{id}/permissions` | Update role permissions | +| `GET` | `/api/permissions` | List all permissions | +| `POST` | `/api/permissions` | Create permission | +| `DELETE` | `/api/permissions/{id}` | Delete permission | + +### 26.3 User Role Assignment (NEW -- Implemented) + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-UROLE-01 | List users with their assigned roles | `/admin/user-roles` | Admin | +| FR-UROLE-02 | View roles for a specific user | `/admin/user-roles` | Admin | +| FR-UROLE-03 | Assign/remove roles for a user | `/admin/user-roles` | Admin | +| FR-UROLE-04 | Toggle individual role on/off for a user | `/admin/user-roles` | Admin | + +**API Endpoints:** + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/users/with-roles` | List users with role details | +| `GET` | `/api/users/{id}/roles` | Get roles for a user | +| `PATCH` | `/api/users/{id}/roles` | Update user roles | +| `POST` | `/api/users/{id}/roles/toggle` | Toggle a single role | + +### 26.4 Authority Matrix (NEW -- Implemented) + +A visual matrix showing all roles vs. all permissions, allowing administrators to toggle permission assignments visually. + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-AUTH-01 | Display role-permission matrix (roles as columns, permissions as rows) | `/admin/authority-matrix` | Admin | +| FR-AUTH-02 | Toggle individual permission cells (grant/revoke) | `/admin/authority-matrix` | Admin | +| FR-AUTH-03 | View user-specific authority matrix | `/admin/authority-matrix` | Admin | + +**API Endpoints:** + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/authority-matrix` | Get full role-permission matrix | +| `POST` | `/api/authority-matrix/toggle` | Toggle a permission cell | +| `GET` | `/api/user-authority-matrix` | Get user-level authority view | + +--- + +# Part VII -- Support and Commercial + +## 27. Ticketing System (Production Parity) + +> **Implementation:** `tickets.service.ts` | `encoach_api/controllers/ticket.py` | `AdminTickets.tsx` + +| ID | Requirement | +|----|-------------| +| FR-TCK-01 | Filters: Status, Type, Assignee, Source (All/Webpage/Platform) | +| FR-TCK-02 | Sort by date | +| FR-TCK-03 | Columns: ID, Type, Reporter, Source, Date, Subject, Status, Assignee, Corporate | +| FR-TCK-04 | Pagination | + +--- + +## 28. Subscriptions and Payments + +> **Implementation:** `subscriptions.service.ts` | `encoach_api/controllers/subscription.py` | `AdminPaymentRecord.tsx`, `Payment.tsx` + +### 28.1 Billing Models + +| Model | Description | Payment | +|-------|-------------|---------| +| **Institutional License** | UTAS or corporate entity purchases bulk licenses | Invoice-based or Stripe/PayPal | +| **Individual Subscription** | Freelance student purchases access per subject or platform-wide | Stripe, PayPal, or Paymob | +| **Package** | Predefined bundles (e.g., "IELTS Complete", "Math + IT Bundle") | Per-package pricing | + +### 28.2 Functional Requirements (Production Parity) + +| ID | Requirement | Route | +|----|-------------|-------| +| FR-PAY-01 | Payment page with entity context | `/payment` | +| FR-PAY-02 | Payment record / ledger | `/payment-record` | +| FR-PAY-03 | Package listing | `/api/packages` | +| FR-PAY-04 | Stripe checkout flow | `/api/stripe` | +| FR-PAY-05 | PayPal checkout flow | `/api/paypal` | +| FR-PAY-06 | Paymob checkout flow | `/api/paymob` | +| FR-PAY-07 | Webhook handling (Stripe, PayPal, Paymob) | `/api/*/webhook` | + +--- + +## 29. Training Content + +> **Implementation:** `training.service.ts` | `encoach_api/controllers/training.py` | `AdminTrainingVocabulary.tsx`, `AdminTrainingGrammar.tsx` + +### 29.1 Existing (Production Parity) + +| ID | Requirement | Route | +|----|-------------|-------| +| FR-TRN-01 | Training hub with entity/user/time filters | `/training` | +| FR-TRN-02 | Vocabulary training (progress, recommended, sections) | `/training/vocabulary` | +| FR-TRN-03 | Grammar training (parallel structure) | `/training/grammar` | +| FR-TRN-04 | Record view with entity/user/time/assignment filters | `/record` | + +### 29.2 New (Subject-Specific Tips) + +| ID | Requirement | +|----|-------------| +| FR-TRN-05 | **NEW:** Math-specific training tips via FAISS (algebra, geometry, statistics indices) | +| FR-TRN-06 | **NEW:** IT-specific training tips via FAISS (networking, databases, programming indices) | +| FR-TRN-07 | **NEW:** Personalized post-exam tips using subject-specific FAISS + GPT-4o selection | + +--- + +# Part VIII -- Institutional LMS (OpenEduCat) + +All LMS features in this part are backed by OpenEduCat community modules (ported to Odoo 19). The `encoach_lms_api` module extends these models and exposes them via REST API to the React frontend. + +--- + +## 30. Academic Year and Term Management + +> **Implementation:** `academic.service.ts` | `encoach_lms_api/controllers/academic.py` | `AdminAcademicYears.tsx` + +### 30.1 Overview + +Academic years define the institutional calendar. Each year contains terms (semesters, quarters) that govern course scheduling, batch periods, and exam sessions. + +### 30.2 Data Models (OpenEduCat) + +**`op.academic.year`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Academic year name (e.g., "2026-2027") | +| `start_date` | Date | Year start | +| `end_date` | Date | Year end | +| `term_structure` | Selection | `two_sem`, `two_sem_qua`, `three_sem`, `four_Quarter`, `final_year`, `others` | +| `academic_term_ids` | One2many | Terms within this year | + +**`op.academic.term`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Term name (e.g., "Semester 1") | +| `term_start_date` | Date | Term start | +| `term_end_date` | Date | Term end | +| `academic_year_id` | Many2one | Parent academic year | +| `parent_term` | Many2one | Parent term (for quarters within semesters) | + +### 30.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-AY-01 | List academic years with terms | `/admin/academic-years` | Admin | +| FR-AY-02 | Create academic year with term structure selection | `/admin/academic-years` | Admin | +| FR-AY-03 | Auto-generate terms based on selected structure | `/admin/academic-years` | Admin | +| FR-AY-04 | Edit/delete academic years and terms | `/admin/academic-years` | Admin | +| FR-AY-05 | Link batches and courses to academic terms | Related pages | Admin | + +### 30.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/academic-years` | List academic years | +| `POST` | `/api/academic-years` | Create academic year | +| `GET` | `/api/academic-years/{id}` | Get year with terms | +| `PATCH` | `/api/academic-years/{id}` | Update year | +| `DELETE` | `/api/academic-years/{id}` | Delete year | +| `POST` | `/api/academic-years/{id}/generate-terms` | Auto-generate terms from structure | +| `GET` | `/api/academic-terms` | List terms (filter by year) | +| `POST` | `/api/academic-terms` | Create term | +| `PATCH` | `/api/academic-terms/{id}` | Update term | +| `DELETE` | `/api/academic-terms/{id}` | Delete term | + +--- + +## 31. Department Management + +> **Implementation:** `academic.service.ts` | `encoach_lms_api/controllers/departments.py` | `AdminDepartments.tsx` + +### 31.1 Overview + +Departments organize faculty, courses, and subjects into academic units (e.g., "Department of Mathematics", "Department of IT"). + +### 31.2 Data Model (OpenEduCat) + +**`op.department`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Department name | +| `code` | Char | Department code | +| `parent_id` | Many2one | Parent department (for hierarchy) | + +### 31.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-DEPT-01 | List departments | `/admin/departments` | Admin | +| FR-DEPT-02 | Create/edit department | `/admin/departments` | Admin | +| FR-DEPT-03 | Delete department | `/admin/departments` | Admin | +| FR-DEPT-04 | Assign department to courses and faculty | Related pages | Admin | + +### 31.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/departments` | List departments | +| `POST` | `/api/departments` | Create department | +| `PATCH` | `/api/departments/{id}` | Update department | +| `DELETE` | `/api/departments/{id}` | Delete department | + +--- + +## 32. Admission and Enrollment + +> **Implementation:** `admission.service.ts` | `encoach_lms_api/controllers/admissions.py` | `AdminAdmissionRegister.tsx`, `AdminAdmissions.tsx` + +### 32.1 Overview + +The admission workflow manages student applications from submission through confirmation to enrollment. Admission registers define open enrollment windows. + +### 32.2 Data Models (OpenEduCat) + +**`op.admission.register`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Register name (e.g., "Fall 2026 Admissions") | +| `course_id` | Many2one | Target course | +| `start_date` | Date | Application window start | +| `end_date` | Date | Application window end | +| `min_count` | Integer | Minimum applications to proceed | +| `max_count` | Integer | Maximum applications accepted | +| `state` | Selection | `draft`, `confirm`, `cancel`, `done` | +| `product_id` | Many2one | Fee product for admission | + +**`op.admission`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Applicant name | +| `application_number` | Char | Auto-generated application number | +| `register_id` | Many2one | Admission register | +| `course_id` | Many2one | Applied course | +| `batch_id` | Many2one | Target batch | +| `first_name` | Char | First name | +| `middle_name` | Char | Middle name | +| `last_name` | Char | Last name | +| `email` | Char | Email | +| `phone` | Char | Phone | +| `birth_date` | Date | Date of birth | +| `gender` | Selection | `m`, `f`, `o` | +| `nationality` | Many2one | Country | +| `state` | Selection | `draft`, `submit`, `confirm`, `admission`, `reject`, `cancel`, `done` | +| `fees` | Float | Admission fee amount | +| `image` | Binary | Applicant photo | +| `student_id` | Many2one | Created student record (after admission) | + +### 32.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-ADM-01 | List admission registers with status | `/admin/admission-register` | Admin | +| FR-ADM-02 | Create/edit admission register (course, dates, capacity) | `/admin/admission-register` | Admin | +| FR-ADM-03 | Open/close admission register | `/admin/admission-register` | Admin | +| FR-ADM-04 | List admissions with filters (status, course, register) | `/admin/admissions` | Admin | +| FR-ADM-05 | View admission detail | `/admin/admissions/:id` | Admin | +| FR-ADM-06 | Transition admission status (submit, confirm, admit, reject) | `/admin/admissions/:id` | Admin | +| FR-ADM-07 | On admit: auto-create `op.student` and `op.student.course` records | Backend | System | +| FR-ADM-08 | Public admission application form | `/apply` | Public/Student | +| FR-ADM-09 | Applicant status tracking | `/apply/status` | Public | + +### 32.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/admission-registers` | List registers | +| `POST` | `/api/admission-registers` | Create register | +| `PATCH` | `/api/admission-registers/{id}` | Update register | +| `POST` | `/api/admission-registers/{id}/confirm` | Confirm register | +| `POST` | `/api/admission-registers/{id}/close` | Close register | +| `GET` | `/api/admissions` | List admissions | +| `GET` | `/api/admissions/{id}` | Get admission detail | +| `POST` | `/api/admissions` | Submit admission application | +| `POST` | `/api/admissions/{id}/submit` | Submit for review | +| `POST` | `/api/admissions/{id}/confirm` | Confirm admission | +| `POST` | `/api/admissions/{id}/admit` | Admit applicant (creates student) | +| `POST` | `/api/admissions/{id}/reject` | Reject admission | + +--- + +## 33. Subject Registration + +> **Implementation:** `institutional-exam.service.ts` | `encoach_lms_api/controllers/subject_registration.py` | `StudentSubjectRegistration.tsx` + +### 33.1 Overview + +Within enrolled courses, students register for specific subjects. This is required for timetable, attendance, and exam eligibility. + +### 33.2 Data Model (OpenEduCat) + +**`op.subject.registration`** + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Student | +| `course_id` | Many2one | Course | +| `batch_id` | Many2one | Batch | +| `subject_ids` | Many2many | Selected subjects | +| `min_unit_load` | Float | Minimum units from course config | +| `max_unit_load` | Float | Maximum units from course config | +| `state` | Selection | `draft`, `confirm`, `reject`, `done` | + +### 33.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-SR-01 | Students view available subjects for enrolled courses | `/student/subject-registration` | Student | +| FR-SR-02 | Students select subjects within unit load limits | `/student/subject-registration` | Student | +| FR-SR-03 | Submit registration for approval | `/student/subject-registration` | Student | +| FR-SR-04 | Admin/teacher view and approve/reject registrations | `/admin/students` | Admin | +| FR-SR-05 | Confirmed registration updates `op.student.course.subject_ids` | Backend | System | + +### 33.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/subject-registrations` | List registrations (filter by student, course, status) | +| `POST` | `/api/subject-registrations` | Create registration | +| `PATCH` | `/api/subject-registrations/{id}` | Update subjects | +| `POST` | `/api/subject-registrations/{id}/confirm` | Confirm registration | +| `POST` | `/api/subject-registrations/{id}/reject` | Reject registration | +| `GET` | `/api/subject-registrations/available` | Get available subjects for current student | + +--- + +## 34. Institutional Exam Sessions + +> **Implementation:** `institutional-exam.service.ts` | `encoach_lms_api/controllers/inst_exams.py` | `AdminExamSessions.tsx`, `AdminMarksheets.tsx` + +### 34.1 Overview + +Institutional exam sessions group traditional exams (midterms, finals) for a course/batch. These are separate from EnCoach AI-powered exams. They use the OpenEduCat exam, marksheet, and grading system. + +### 34.2 Data Models (OpenEduCat) + +**`op.exam.session`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Session name (e.g., "Fall 2026 Midterms") | +| `course_id` | Many2one | Course | +| `batch_id` | Many2one | Batch | +| `exam_code` | Char | Session code | +| `start_date` | Date | Session start | +| `end_date` | Date | Session end | +| `exam_type` | Many2one | Exam type (midterm, final, quiz) | +| `evaluation_type` | Selection | `normal` or `grade` | +| `venue` | Many2one | Venue partner | +| `state` | Selection | `draft`, `schedule`, `held`, `cancel`, `done` | +| `exam_ids` | One2many | Exams in this session | + +**`op.exam` (institutional)** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Exam name | +| `session_id` | Many2one | Parent session | +| `subject_id` | Many2one | Subject being examined | +| `exam_code` | Char | Exam code | +| `start_time` | Datetime | Exam start | +| `end_time` | Datetime | Exam end | +| `total_marks` | Integer | Maximum marks | +| `min_marks` | Integer | Passing marks | +| `state` | Selection | `draft`, `schedule`, `held`, `result_updated`, `cancel`, `done` | +| `responsible_id` | Many2many | Responsible faculty | +| `attendees_line` | One2many | Exam attendees with marks | + +**`op.exam.type`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Type name (Midterm, Final, Quiz, Lab) | + +**`op.exam.room`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Room name | +| `classroom_id` | Many2one | Linked classroom | +| `capacity` | Integer | Room capacity | + +**`op.exam.attendees`** + +| Field | Type | Description | +|-------|------|-------------| +| `exam_id` | Many2one | Exam | +| `student_id` | Many2one | Student | +| `room_id` | Many2one | Assigned room | +| `marks` | Integer | Obtained marks | +| `status` | Selection | `pass`, `fail` (computed from marks vs min_marks) | + +**`op.marksheet.register`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Register name | +| `exam_session_id` | Many2one | Exam session | +| `marksheet_line` | One2many | Marksheet lines per student | +| `result_template_id` | Many2one | Result template | +| `state` | Selection | `draft`, `validated`, `cancelled` | +| `total_pass` | Integer | Computed pass count | +| `total_failed` | Integer | Computed fail count | + +**`op.marksheet.line`** + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Student | +| `marksheet_reg_id` | Many2one | Parent register | +| `result_line` | One2many | Per-exam results | +| `total_marks` | Integer | Computed total | +| `percentage` | Float | Computed percentage | +| `grade` | Char | Computed grade (if grade evaluation) | +| `status` | Selection | `pass`, `fail` (computed) | + +**`op.result.line`** + +| Field | Type | Description | +|-------|------|-------------| +| `marksheet_line_id` | Many2one | Parent marksheet line | +| `exam_id` | Many2one | Exam | +| `student_id` | Many2one | Student | +| `marks` | Integer | Marks obtained | +| `grade` | Char | Computed grade | +| `status` | Selection | `pass`, `fail` (computed from marks vs min_marks) | + +**`op.result.template`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Template name | +| `exam_session_id` | Many2one | Exam session | +| `grade_ids` | Many2many | Grade configuration rules | +| `result_date` | Date | Result publication date | +| `state` | Selection | `draft`, `result_generated` | + +**`op.grade.configuration`** + +| Field | Type | Description | +|-------|------|-------------| +| `min_per` | Integer | Minimum percentage | +| `max_per` | Integer | Maximum percentage | +| `result` | Char | Grade display (e.g., "A", "B+", "Pass") | + +### 34.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-IEX-01 | List exam sessions with status filters | `/admin/exam-sessions` | Admin | +| FR-IEX-02 | Create exam session (course, batch, dates, type) | `/admin/exam-sessions` | Admin | +| FR-IEX-03 | Add exams to session (subject, time, marks) | `/admin/exam-sessions` | Admin | +| FR-IEX-04 | Schedule and manage session state transitions | `/admin/exam-sessions` | Admin | +| FR-IEX-05 | Enter marks for exam attendees | `/admin/exam-sessions` | Admin/Teacher | +| FR-IEX-06 | Configure grade scales | `/admin/marksheets` | Admin | +| FR-IEX-07 | Create result templates and generate marksheets | `/admin/marksheets` | Admin | +| FR-IEX-08 | View marksheet results (pass/fail, grades, percentages) | `/admin/marksheets` | Admin | +| FR-IEX-09 | Students view institutional exam results | `/student/grades` | Student | + +### 34.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/inst-exam-sessions` | List exam sessions | +| `POST` | `/api/inst-exam-sessions` | Create session | +| `GET` | `/api/inst-exam-sessions/{id}` | Get session with exams | +| `PATCH` | `/api/inst-exam-sessions/{id}` | Update session | +| `DELETE` | `/api/inst-exam-sessions/{id}` | Delete session | +| `POST` | `/api/inst-exam-sessions/{id}/schedule` | Schedule session | +| `POST` | `/api/inst-exam-sessions/{id}/done` | Mark session done | +| `POST` | `/api/inst-exams` | Add exam to session | +| `PATCH` | `/api/inst-exams/{id}` | Update exam | +| `POST` | `/api/inst-exams/{id}/attendees` | Add attendees | +| `PATCH` | `/api/inst-exams/{id}/marks` | Enter marks | +| `GET` | `/api/exam-types` | List exam types | +| `POST` | `/api/exam-types` | Create exam type | +| `GET` | `/api/grade-config` | List grade configurations | +| `POST` | `/api/grade-config` | Create grade config | +| `GET` | `/api/result-templates` | List result templates | +| `POST` | `/api/result-templates` | Create result template | +| `POST` | `/api/result-templates/{id}/generate` | Generate marksheets | +| `GET` | `/api/marksheets` | List marksheets | +| `GET` | `/api/marksheets/{id}` | Get marksheet with results | +| `POST` | `/api/marksheets/{id}/validate` | Validate marksheet | + +--- + +## 35. Assignment File Submissions + +> **Implementation:** `institutional-exam.service.ts` | `encoach_lms_api/controllers/course_assignments.py` | `TeacherAssignments.tsx`, `StudentAssignments.tsx` + +### 35.1 Overview + +Traditional course assignments where students submit files and teachers grade them. Coexists with EnCoach exam-wrapper assignments (`encoach.assignment`). + +### 35.2 Data Models (OpenEduCat) + +**`grading.assignment.type`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Type name (Homework, Project, Lab Report, Presentation) | + +**`grading.assignment`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Assignment title | +| `course_id` | Many2one | Course | +| `subject_id` | Many2one | Subject | +| `issued_date` | Datetime | Issue date | +| `assignment_type` | Many2one | Assignment type | +| `faculty_id` | Many2one | Issuing faculty | +| `point` | Float | Maximum points | + +**`op.assignment` (extends `grading.assignment`)** + +| Field | Type | Description | +|-------|------|-------------| +| `batch_id` | Many2one | Batch | +| `marks` | Float | Maximum marks | +| `description` | Text | Assignment description | +| `state` | Selection | `draft`, `publish`, `finish`, `cancel` | +| `submission_date` | Datetime | Submission deadline | +| `allocation_ids` | Many2many | Allocated students | +| `assignment_sub_line` | One2many | Student submissions | +| `reviewer` | Many2one | Reviewing faculty | + +**`op.assignment.sub.line`** + +| Field | Type | Description | +|-------|------|-------------| +| `assignment_id` | Many2one | Parent assignment | +| `student_id` | Many2one | Submitting student | +| `description` | Text | Submission notes | +| `submission_date` | Datetime | Actual submission time | +| `attachment_ids` | Many2many | Uploaded files | +| `marks` | Float | Awarded marks | +| `state` | Selection | `draft`, `submit`, `accept`, `reject`, `change_req` | +| `faculty_id` | Many2one | Grading faculty | +| `note` | Text | Faculty feedback | + +### 35.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-SUB-01 | Teacher creates course assignment with description, deadline, files | `/teacher/assignments` | Teacher | +| FR-SUB-02 | Teacher publishes assignment (visible to allocated students) | `/teacher/assignments` | Teacher | +| FR-SUB-03 | Student views assigned course assignments with deadlines | `/student/assignments` | Student | +| FR-SUB-04 | Student uploads files as submission | `/student/assignments` | Student | +| FR-SUB-05 | Teacher views submissions per assignment | `/teacher/assignments/:id` | Teacher | +| FR-SUB-06 | Teacher grades submission (marks, feedback, accept/reject/change request) | `/teacher/assignments/:id` | Teacher | +| FR-SUB-07 | Admin views all course assignments across batches | `/admin/assignments` | Admin | + +### 35.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/course-assignments` | List course assignments | +| `POST` | `/api/course-assignments` | Create assignment | +| `GET` | `/api/course-assignments/{id}` | Get assignment with submissions | +| `PATCH` | `/api/course-assignments/{id}` | Update assignment | +| `POST` | `/api/course-assignments/{id}/publish` | Publish assignment | +| `POST` | `/api/course-assignments/{id}/finish` | Close assignment | +| `GET` | `/api/course-assignments/{id}/submissions` | List submissions | +| `POST` | `/api/course-assignments/{id}/submit` | Student submits (multipart file upload) | +| `PATCH` | `/api/submissions/{id}` | Grade submission (marks, feedback, status) | +| `GET` | `/api/assignment-types` | List assignment types | +| `POST` | `/api/assignment-types` | Create assignment type | + +--- + +# Part VIII-B -- OpenEduCat Enterprise Features + +The following sections cover additional institutional features implemented by the developer beyond the original SRS. These features leverage OpenEduCat Enterprise modules and extend the platform with student lifecycle management, financial tracking, library services, and facility management. + +--- + +## 36. Student Leave Management + +> **Implementation:** `student-leave.service.ts` | `encoach_lms_api/controllers/student_leave.py` | `AdminStudentLeave.tsx` + +### 36.1 Overview + +Students submit leave requests with a type, date range, and justification. Administrators approve or reject requests. Leave types are configurable. + +### 36.2 Data Models + +**`op.student.leave.request`** (OpenEduCat Enterprise) + +| Field | Type | Description | +|-------|------|-------------| +| `request_number` | Char | Auto-generated request number | +| `student_id` | Many2one | Requesting student | +| `leave_type` | Many2one | Leave type reference | +| `start_date` | Date | Leave start | +| `end_date` | Date | Leave end | +| `duration` | Float | Computed duration in days | +| `description` | Text | Justification | +| `state` | Selection | `draft`, `confirm`, `validate`, `approve`, `refuse`, `cancel` | +| `approve_date` | Date | Date of approval | + +**`op.student.leave.type`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Leave type name (e.g., Medical, Personal, Academic) | + +### 36.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-SL-01 | List student leave requests with status filters | `/admin/student-leave` | Admin | +| FR-SL-02 | Create leave request (student, type, dates, description) | `/admin/student-leave` | Admin/Student | +| FR-SL-03 | Approve/reject leave request with state transition | `/admin/student-leave` | Admin | +| FR-SL-04 | Manage leave types (CRUD) | `/admin/student-leave` | Admin | + +### 36.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/student-leaves` | List leave requests | +| `POST` | `/api/student-leaves` | Create leave request | +| `PATCH` | `/api/student-leaves/{id}` | Update leave request | +| `POST` | `/api/student-leaves/{id}/approve` | Approve request | +| `POST` | `/api/student-leaves/{id}/reject` | Reject request | +| `GET` | `/api/student-leave-types` | List leave types | +| `POST` | `/api/student-leave-types` | Create leave type | + +--- + +## 37. Fees Management + +> **Implementation:** `fees.service.ts` | `encoach_lms_api/controllers/fees.py` | `AdminFees.tsx` + +### 37.1 Overview + +Institutional fee plans track student financial obligations per course. The system tracks total, paid, and remaining amounts per student, linked to invoicing. + +### 37.2 Data Models + +**`op.fees.plan`** (OpenEduCat Enterprise) + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Student | +| `course_id` | Many2one | Course | +| `total_amount` | Float | Total fee amount | +| `paid_amount` | Float | Amount paid to date | +| `remaining_amount` | Float | Computed remaining balance | +| `state` | Selection | Fee plan state | + +**`op.student.fees.details`** + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Student | +| `amount` | Float | Fee amount | +| `date` | Date | Fee date | +| `state` | Selection | Payment state | +| `invoice_state` | Selection | Invoice state | +| `product_name` | Char | Fee product name | + +**`op.fees.terms`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Term name | +| `no_days` | Integer | Number of days for payment | +| `line_ids` | One2many | Fee term lines | + +### 37.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-FEES-01 | List fees plans with student and course details | `/admin/fees` | Admin | +| FR-FEES-02 | View individual student fees with payment history | `/admin/fees` | Admin | +| FR-FEES-03 | View fees terms configuration | `/admin/fees` | Admin | + +### 37.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/fees-plans` | List fee plans | +| `GET` | `/api/fees-plans/{id}` | Get fee plan detail | +| `GET` | `/api/student-fees` | List student fee details | +| `GET` | `/api/fees-terms` | List fees terms | + +--- + +## 38. Lessons Management + +> **Implementation:** `lesson.service.ts` | `encoach_lms_api/controllers/lessons.py` | `AdminLessons.tsx` + +### 38.1 Overview + +Lessons represent individual teaching sessions within timetable sessions. They link subjects to specific timetable slots and track the topic covered. + +### 38.2 Data Model + +**`op.session.lesson`** (OpenEduCat Enterprise) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Lesson name | +| `lesson_topic` | Char | Topic covered | +| `course_id` | Many2one | Course | +| `batch_id` | Many2one | Batch | +| `subject_id` | Many2one | Subject | +| `session_id` | Many2one | Timetable session | +| `faculty_id` | Many2one | Teaching faculty | +| `start_datetime` | Datetime | Lesson start | +| `end_datetime` | Datetime | Lesson end | + +### 38.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-LSN-01 | List lessons with subject and session details | `/admin/lessons` | Admin | +| FR-LSN-02 | Create lesson (name, topic, course, batch, subject, session, faculty, times) | `/admin/lessons` | Admin | +| FR-LSN-03 | Update/delete lessons | `/admin/lessons` | Admin | + +### 38.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/lessons` | List lessons | +| `POST` | `/api/lessons` | Create lesson | +| `PATCH` | `/api/lessons/{id}` | Update lesson | +| `DELETE` | `/api/lessons/{id}` | Delete lesson | + +--- + +## 39. Gradebook and Grading Assignments + +> **Implementation:** `gradebook.service.ts` | `encoach_lms_api/controllers/gradebook.py` | `AdminGradebook.tsx` + +### 39.1 Overview + +The gradebook aggregates student marks across courses and academic years. Grading assignments define assessment items with marks and sequences. Gradebook lines show per-student, per-assignment results with percentages. + +### 39.2 Data Models + +**`op.gradebook`** (OpenEduCat Enterprise) + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Student | +| `course_id` | Many2one | Course | +| `academic_year_id` | Many2one | Academic year | +| `line_ids` | One2many | Gradebook lines | + +**`op.gradebook.line`** + +| Field | Type | Description | +|-------|------|-------------| +| `gradebook_id` | Many2one | Parent gradebook | +| `student_name` | Char | Related student name | +| `assignment_name` | Char | Related assignment name | +| `marks` | Float | Marks obtained | +| `percentage` | Float | Computed percentage | +| `state` | Selection | Line state | + +**`grading.assignment`** (extended) + +| Field | Type | Description | +|-------|------|-------------| +| `sequence` | Char | Assignment sequence code | +| `name` | Char | Assignment name | +| `course_id` | Many2one | Course | +| `subject_id` | Many2one | Subject | +| `state` | Selection | Assignment state | +| `issued_date` | Date | Issue date | + +### 39.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-GB-01 | List gradebooks filtered by course and academic year | `/admin/gradebook` | Admin | +| FR-GB-02 | View gradebook lines per student with marks and percentages | `/admin/gradebook` | Admin | +| FR-GB-03 | Create/update/delete grading assignments | `/admin/gradebook` | Admin | + +### 39.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/gradebooks` | List gradebooks | +| `GET` | `/api/gradebook-lines` | List gradebook lines | +| `GET` | `/api/grading-assignments` | List grading assignments | +| `POST` | `/api/grading-assignments` | Create grading assignment | +| `PATCH` | `/api/grading-assignments/{id}` | Update grading assignment | +| `DELETE` | `/api/grading-assignments/{id}` | Delete grading assignment | + +--- + +## 40. Student Progress Tracking + +> **Implementation:** `student-progress.service.ts` | `encoach_lms_api/controllers/student_progress.py` | `AdminStudentProgress.tsx` + +### 40.1 Overview + +Aggregate view of student academic progression combining attendance, assignment completion, and marksheet results into a unified tracking interface. + +### 40.2 Data Model + +**`op.student.progression`** (OpenEduCat Enterprise) + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Student | +| `total_attendance` | Float | Computed total attendance percentage | +| `total_assignment` | Float | Computed total assignment count/score | +| `total_marksheet_line` | Float | Computed total marksheet entries | + +### 40.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-SP-01 | List student progress with attendance, assignment, and marksheet aggregates | `/admin/student-progress` | Admin | +| FR-SP-02 | Filter by course, batch, or individual student | `/admin/student-progress` | Admin | + +### 40.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/student-progress` | List student progression records | + +--- + +## 41. Library Management + +> **Implementation:** `library.service.ts` | `encoach_lms_api/controllers/library.py` | `AdminLibrary.tsx` + +### 41.1 Overview + +Institutional library management supporting media cataloging, borrowing (movements), and library card issuance. Tracks media items (books, journals, CDs), their circulation, and student/faculty borrowing history. + +### 41.2 Data Models + +**`op.media`** (OpenEduCat Library) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Media title | +| `isbn` | Char | ISBN number | +| `author` | Char | Author name | +| `edition` | Char | Edition | +| `media_type` | Selection | Media type (book, journal, CD, etc.) | + +**`op.media.movement`** + +| Field | Type | Description | +|-------|------|-------------| +| `media_id` | Many2one | Media item | +| `student_id` | Many2one | Borrowing student | +| `faculty_id` | Many2one | Issuing faculty | +| `issued_date` | Date | Issue date | +| `return_date` | Date | Return date | +| `state` | Selection | Movement state (issued, returned, overdue) | + +**`op.library.card`** + +| Field | Type | Description | +|-------|------|-------------| +| `number` | Char | Card number | +| `student_id` | Many2one | Cardholder student | +| `faculty_id` | Many2one | Issuing faculty | + +### 41.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-LIB-01 | Catalog media items with ISBN, author, edition | `/admin/library` | Admin | +| FR-LIB-02 | Track media movements (issue, return) | `/admin/library` | Admin | +| FR-LIB-03 | Issue and manage library cards | `/admin/library` | Admin | +| FR-LIB-04 | Delete media items | `/admin/library` | Admin | + +### 41.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/library/media` | List media items | +| `POST` | `/api/library/media` | Create media item | +| `DELETE` | `/api/library/media/{id}` | Delete media item | +| `GET` | `/api/library/movements` | List movements | +| `POST` | `/api/library/movements` | Create movement (issue) | +| `PATCH` | `/api/library/movements/{id}` | Update movement | +| `POST` | `/api/library/movements/{id}/return` | Return media | +| `GET` | `/api/library/cards` | List library cards | +| `POST` | `/api/library/cards` | Create library card | + +--- + +## 42. Activity Management + +> **Implementation:** `activity.service.ts` | `encoach_lms_api/controllers/activities.py` | `AdminActivities.tsx` + +### 42.1 Overview + +Tracks extracurricular and academic activities per student. Activity types are configurable (sports, cultural, academic, volunteer, etc.). + +### 42.2 Data Models + +**`op.activity`** (OpenEduCat Activity) + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Student | +| `type_id` | Many2one | Activity type | +| `date` | Date | Activity date | +| `description` | Text | Activity description | + +**`op.activity.type`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Type name | + +### 42.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-ACT-01 | List student activities with type and date | `/admin/activities` | Admin | +| FR-ACT-02 | Create/update/delete activities | `/admin/activities` | Admin | +| FR-ACT-03 | Manage activity types (CRUD) | `/admin/activities` | Admin | + +### 42.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/activities` | List activities | +| `POST` | `/api/activities` | Create activity | +| `PATCH` | `/api/activities/{id}` | Update activity | +| `DELETE` | `/api/activities/{id}` | Delete activity | +| `GET` | `/api/activity-types` | List activity types | +| `POST` | `/api/activity-types` | Create activity type | +| `DELETE` | `/api/activity-types/{id}` | Delete activity type | + +--- + +## 43. Facility and Asset Management + +> **Implementation:** `facility.service.ts` | `encoach_lms_api/controllers/facilities.py` | `AdminFacilities.tsx` + +### 43.1 Overview + +Manages institutional facilities (buildings, labs, rooms) and their associated assets (equipment, furniture). Facilities can be linked to classrooms and timetable sessions. + +### 43.2 Data Models + +**`op.facility`** (OpenEduCat Facility) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Facility name | +| `code` | Char | Facility code | + +**`op.facility.line`** (Asset) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Asset name | +| `code` | Char | Asset code | +| `product_name` | Char | Product description | + +### 43.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-FAC-01 | List facilities with codes | `/admin/facilities` | Admin | +| FR-FAC-02 | Create/update/delete facilities | `/admin/facilities` | Admin | +| FR-FAC-03 | List and manage assets within facilities | `/admin/facilities` | Admin | + +### 43.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/facilities` | List facilities | +| `POST` | `/api/facilities` | Create facility | +| `PATCH` | `/api/facilities/{id}` | Update facility | +| `DELETE` | `/api/facilities/{id}` | Delete facility | +| `GET` | `/api/assets` | List assets | +| `POST` | `/api/assets` | Create asset | +| `DELETE` | `/api/assets/{id}` | Delete asset | + +--- + +# Part IX -- Courseware and Content Delivery + +This part covers the Moodle-style structured course delivery system: chapter-based content organization, material management, and AI-powered course content generation. + +--- + +## 44. Course Chapters + +> **Implementation:** `courseware.service.ts` | `encoach_lms_api/controllers/courseware.py` | `TeacherCourseChapters.tsx`, `StudentCourseChapterView.tsx` + +### 44.1 Overview + +Courses are divided into chapters (modules). Teachers create chapters with scheduled start dates, content materials, and lock/unlock controls. Students progress through chapters sequentially or as unlocked by the teacher. + +### 44.2 Data Model (`encoach.course.chapter`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Chapter title | +| `course_id` | Many2one | Parent course (`op.course`) | +| `sequence` | Integer | Display order | +| `description` | Text | Chapter description | +| `start_date` | Datetime | Scheduled start date | +| `end_date` | Datetime | Optional end date | +| `unlock_mode` | Selection | `auto_date` (unlock when start_date reached), `manual` (teacher clicks), `prerequisite` (previous chapter completed) | +| `is_unlocked` | Boolean | Current unlock status | +| `topic_id` | Many2one | Optional link to `encoach.topic` (bridges to adaptive engine) | +| `material_ids` | One2many | Chapter materials | +| `assignment_ids` | Many2many | Linked assignments | +| `exam_ids` | Many2many | Linked exams/quizzes | +| `active` | Boolean | Soft-delete flag | + +### 44.3 Chapter Progress Model (`encoach.chapter.progress`) + +| Field | Type | Description | +|-------|------|-------------| +| `student_id` | Many2one | Student | +| `chapter_id` | Many2one | Chapter | +| `status` | Selection | `not_started`, `in_progress`, `completed` | +| `started_at` | Datetime | When student first accessed | +| `completed_at` | Datetime | When marked complete | +| `materials_completed` | Integer | Count of materials viewed/downloaded | +| `materials_total` | Integer | Total materials in chapter | + +### 44.4 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-CH-01 | Teacher creates chapters for a course with name, description, sequence | `/teacher/courses/:id/chapters` | Teacher | +| FR-CH-02 | Teacher sets chapter start date and unlock mode (auto/manual/prerequisite) | `/teacher/courses/:id/chapters` | Teacher | +| FR-CH-03 | Teacher reorders chapters via drag-and-drop | `/teacher/courses/:id/chapters` | Teacher | +| FR-CH-04 | Teacher manually unlocks/locks a chapter | `/teacher/courses/:id/chapters` | Teacher | +| FR-CH-05 | System auto-unlocks chapters when start_date is reached (cron job) | Backend | System | +| FR-CH-06 | Student sees unlocked chapters on course detail page | `/student/courses/:id` | Student | +| FR-CH-07 | Student views chapter content and materials | `/student/courses/:id/chapters/:chapterId` | Student | +| FR-CH-08 | System tracks per-student chapter progress | Backend | System | +| FR-CH-09 | Chapter completion notification sent to student | Backend | System | +| FR-CH-10 | Teacher views chapter progress per student | `/teacher/courses/:id/chapters` | Teacher | + +### 44.5 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/courses/{courseId}/chapters` | List chapters for course | +| `POST` | `/api/courses/{courseId}/chapters` | Create chapter | +| `GET` | `/api/chapters/{id}` | Get chapter detail with materials | +| `PATCH` | `/api/chapters/{id}` | Update chapter | +| `DELETE` | `/api/chapters/{id}` | Delete chapter | +| `POST` | `/api/chapters/{id}/unlock` | Manually unlock chapter | +| `POST` | `/api/chapters/{id}/lock` | Manually lock chapter | +| `PATCH` | `/api/courses/{courseId}/chapters/reorder` | Reorder chapters | +| `GET` | `/api/chapters/{id}/progress` | Get student progress for chapter | +| `POST` | `/api/chapters/{id}/progress/complete` | Mark chapter as completed | + +--- + +## 45. Chapter Materials + +> **Implementation:** `courseware.service.ts` | `encoach_lms_api/controllers/courseware.py` | `TeacherCourseChapters.tsx` + +### 45.1 Overview + +Each chapter contains materials: uploaded files (PDFs, documents), videos, audio, images, hyperlinks, and articles. Teachers control download permissions per material. + +### 45.2 Data Model (`encoach.chapter.material`) + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Material title | +| `chapter_id` | Many2one | Parent chapter | +| `type` | Selection | `pdf`, `document`, `video`, `audio`, `image`, `link`, `article` | +| `file` | Binary | Uploaded file (for pdf, document, video, audio, image) | +| `url` | Char | External URL (for link, article, or external video) | +| `description` | Text | Material description | +| `sequence` | Integer | Display order | +| `allow_download` | Boolean | Whether students can download the file | +| `is_book` | Boolean | Whether this material is a course book (multi-book support) | +| `book_chapters` | Text (JSON) | Book chapter structure (if following original book chapters) | +| `active` | Boolean | Soft-delete flag | + +### 45.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-MAT-01 | Teacher uploads materials (PDF, Word, video, audio, images) per chapter | `/teacher/courses/:id/chapters/:chapterId` | Teacher | +| FR-MAT-02 | Teacher adds external links, articles, hyperlinks | `/teacher/courses/:id/chapters/:chapterId` | Teacher | +| FR-MAT-03 | Teacher uploads books with chapter structure (follow original or custom) | `/teacher/courses/:id/chapters/:chapterId` | Teacher | +| FR-MAT-04 | Teacher sets download enable/disable per material | `/teacher/courses/:id/chapters/:chapterId` | Teacher | +| FR-MAT-05 | Teacher uploads teaching aids (video, audio, pictures, hyperlinks) | `/teacher/courses/:id/chapters/:chapterId` | Teacher | +| FR-MAT-06 | Student views materials for unlocked chapters | `/student/courses/:id/chapters/:chapterId` | Student | +| FR-MAT-07 | Student downloads materials if download is enabled | `/student/courses/:id/chapters/:chapterId` | Student | +| FR-MAT-08 | System tracks which materials a student has viewed/downloaded | Backend | System | + +### 45.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/chapters/{chapterId}/materials` | List materials | +| `POST` | `/api/chapters/{chapterId}/materials` | Upload material (multipart) | +| `PATCH` | `/api/materials/{id}` | Update material metadata | +| `DELETE` | `/api/materials/{id}` | Delete material | +| `GET` | `/api/materials/{id}/download` | Download material file | +| `POST` | `/api/materials/{id}/viewed` | Mark material as viewed by student | +| `PATCH` | `/api/chapters/{chapterId}/materials/reorder` | Reorder materials | + +--- + +## 46. AI Workbench for Course Content + +> **Implementation:** `courseware.service.ts` | `encoach_lms_api/controllers/courseware.py` | `TeacherAIWorkbench.tsx` + +### 46.1 Overview + +Teachers use the AI Workbench to generate course content automatically. The AI generates chapters, materials, exercises, and grading rubrics based on high-level requirements input by the teacher. + +### 46.2 AI Workbench Flow + +1. Teacher inputs: topic name, objectives, complexity level, target audience +2. AI generates: chapter structure with learning outcomes, reading content, exercises, multimedia suggestions +3. Teacher reviews generated content +4. Teacher can: modify, regenerate specific sections, add additional context +5. Teacher approves and publishes (follows approval workflow if configured) +6. AI can suggest additional materials based on selected student performance profiles + +### 46.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-WB-01 | Teacher opens AI Workbench from course page | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-02 | Teacher inputs high-level requirements (topic, objectives, complexity) | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-03 | AI generates course outline with chapters and learning outcomes | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-04 | AI generates reading content, exercises, and multimedia for each chapter | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-05 | AI generates grading rubrics based on assignment/exam complexity | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-06 | Teacher reviews and modifies AI-generated content | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-07 | Teacher can prompt AI to regenerate specific sections | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-08 | Teacher selects student profiles for AI to suggest additional materials based on performance | `/teacher/courses/:id/workbench` | Teacher | +| FR-WB-09 | Generated content follows approval workflow before publishing | Backend | System | + +### 46.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `POST` | `/api/workbench/generate-outline` | Generate course outline from requirements | +| `POST` | `/api/workbench/generate-chapter` | Generate content for a specific chapter | +| `POST` | `/api/workbench/generate-rubric` | Generate grading rubric | +| `POST` | `/api/workbench/regenerate` | Regenerate a specific section | +| `POST` | `/api/workbench/suggest-materials` | AI suggests materials based on student profiles | +| `POST` | `/api/workbench/publish` | Publish generated content to course chapters | + +--- + +# Part X -- Communication + +## 47. Discussion Boards + +> **Implementation:** `communication.service.ts` | `encoach_lms_api/controllers/communication.py` | `StudentDiscussions.tsx`, `TeacherDiscussions.tsx` + +### 47.1 Overview + +Per-class discussion boards enable student-to-student and student-to-teacher communication. Discussion boards can be attached to courses, chapters, or assignments. + +### 47.2 Data Models + +**`encoach.discussion.board`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Board title | +| `course_id` | Many2one | Associated course | +| `batch_id` | Many2one | Associated batch (optional) | +| `chapter_id` | Many2one | Associated chapter (optional) | +| `assignment_id` | Many2one | Associated assignment (optional) | +| `is_enabled` | Boolean | Whether teacher has enabled discussions | +| `allow_student_posts` | Boolean | Whether students can create new threads | +| `post_count` | Integer | Computed post count | + +**`encoach.discussion.post`** + +| Field | Type | Description | +|-------|------|-------------| +| `board_id` | Many2one | Parent board | +| `parent_id` | Many2one | Parent post (for replies, nested threads) | +| `author_id` | Many2one | Author user | +| `title` | Char | Post title (for root posts) | +| `content` | Text | Post content (supports markdown) | +| `attachment_ids` | Many2many | File attachments | +| `is_pinned` | Boolean | Pinned by teacher | +| `is_resolved` | Boolean | Marked as resolved (for Q&A) | +| `created_at` | Datetime | Post time | + +### 47.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-DISC-01 | Teacher enables/disables discussion board per course or chapter | `/teacher/courses/:id/discussions` | Teacher | +| FR-DISC-02 | Students create discussion threads | `/student/discussions` | Student | +| FR-DISC-03 | Students and teachers reply to threads (nested replies) | `/student/discussions`, `/teacher/courses/:id/discussions` | Both | +| FR-DISC-04 | Teacher pins important posts | `/teacher/courses/:id/discussions` | Teacher | +| FR-DISC-05 | Teacher marks posts as resolved | `/teacher/courses/:id/discussions` | Teacher | +| FR-DISC-06 | Students view other participants within the same class | `/student/discussions` | Student | +| FR-DISC-07 | File attachments on posts | Both pages | Both | + +### 47.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/discussion-boards` | List boards (filter: course_id, batch_id) | +| `POST` | `/api/discussion-boards` | Create board | +| `PATCH` | `/api/discussion-boards/{id}` | Update board settings | +| `GET` | `/api/discussion-boards/{id}/posts` | List posts for board (paginated) | +| `POST` | `/api/discussion-boards/{id}/posts` | Create post/reply | +| `PATCH` | `/api/posts/{id}` | Update post | +| `DELETE` | `/api/posts/{id}` | Delete post | +| `POST` | `/api/posts/{id}/pin` | Pin/unpin post | +| `POST` | `/api/posts/{id}/resolve` | Mark as resolved | + +--- + +## 48. Announcements + +> **Implementation:** `communication.service.ts` | `encoach_lms_api/controllers/communication.py` | `StudentAnnouncements.tsx`, `TeacherAnnouncements.tsx` + +### 48.1 Overview + +Teachers broadcast announcements to classes. System-wide announcements can be created by administrators. + +### 48.2 Data Model (`encoach.announcement`) + +| Field | Type | Description | +|-------|------|-------------| +| `title` | Char | Announcement title | +| `content` | Text | Announcement body (supports markdown) | +| `author_id` | Many2one | Author | +| `course_id` | Many2one | Target course (null = system-wide) | +| `batch_id` | Many2one | Target batch (null = all batches in course) | +| `priority` | Selection | `normal`, `important`, `urgent` | +| `is_published` | Boolean | Published status | +| `published_at` | Datetime | Publish time | +| `expires_at` | Datetime | Expiry time (optional) | +| `send_email` | Boolean | Also send via email | +| `attachment_ids` | Many2many | File attachments | + +### 48.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-ANN-01 | Teacher creates announcement for class/batch | `/teacher/announcements` | Teacher | +| FR-ANN-02 | Teacher sends announcement via platform and/or email | `/teacher/announcements` | Teacher | +| FR-ANN-03 | Admin creates system-wide announcements | `/admin/announcements` | Admin | +| FR-ANN-04 | Students view announcements on dashboard and dedicated page | `/student/announcements` | Student | +| FR-ANN-05 | Priority-based display (urgent announcements highlighted) | All dashboards | All | + +### 48.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/announcements` | List announcements (filter: course_id, priority) | +| `POST` | `/api/announcements` | Create announcement | +| `PATCH` | `/api/announcements/{id}` | Update announcement | +| `DELETE` | `/api/announcements/{id}` | Delete announcement | +| `POST` | `/api/announcements/{id}/publish` | Publish announcement | + +--- + +## 49. Messaging + +> **Implementation:** `communication.service.ts` | `encoach_lms_api/controllers/communication.py` | `StudentMessages.tsx`, `TeacherMessages.tsx` + +### 49.1 Overview + +Direct messaging between platform users. Teachers can message students individually. Students can message other students within the same class (if allowed). Platform can send emails through linked accounts. + +### 49.2 Data Model (`encoach.message`) + +| Field | Type | Description | +|-------|------|-------------| +| `sender_id` | Many2one | Sender user | +| `recipient_id` | Many2one | Recipient user | +| `subject` | Char | Message subject | +| `content` | Text | Message body | +| `is_read` | Boolean | Read status | +| `read_at` | Datetime | When read | +| `attachment_ids` | Many2many | File attachments | +| `send_email_copy` | Boolean | Also send copy via email | +| `created_at` | Datetime | Sent time | + +### 49.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-MSG-01 | Users send direct messages to other users | `/student/messages`, `/teacher/messages` | All | +| FR-MSG-02 | Inbox with read/unread filtering | `/student/messages` | All | +| FR-MSG-03 | Option to send email copy through the platform | Both pages | All | +| FR-MSG-04 | File attachments on messages | Both pages | All | +| FR-MSG-05 | Students see other participants within same class | `/student/messages` | Student | + +### 49.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/messages` | List messages (inbox, filter: unread) | +| `GET` | `/api/messages/sent` | List sent messages | +| `POST` | `/api/messages` | Send message | +| `GET` | `/api/messages/{id}` | Get message detail (marks as read) | +| `DELETE` | `/api/messages/{id}` | Delete message | +| `GET` | `/api/messages/unread-count` | Get unread message count | + +--- + +# Part XI -- Notifications and FAQ + +## 50. Notification Engine + +> **Implementation:** `notification.service.ts` | `encoach_lms_api/controllers/notification.py` | `AdminNotificationRules.tsx` + +### 50.1 Overview + +Centralized notification system supporting both in-app and email notifications. Notifications are triggered by system events (deadlines, chapter unlocks, result releases, announcements) and can be configured by teachers and admins. + +### 50.2 Data Models + +**`encoach.notification`** + +| Field | Type | Description | +|-------|------|-------------| +| `user_id` | Many2one | Recipient user | +| `title` | Char | Notification title | +| `message` | Text | Notification body | +| `type` | Selection | `deadline`, `chapter_unlock`, `result_release`, `announcement`, `assignment`, `exam`, `message`, `system` | +| `action_url` | Char | URL to redirect to when clicked | +| `is_read` | Boolean | Read status | +| `read_at` | Datetime | When read | +| `channel` | Selection | `in_app`, `email`, `both` | +| `created_at` | Datetime | Created time | + +**`encoach.notification.rule`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Rule name | +| `event_type` | Selection | `assignment_due`, `exam_due`, `chapter_unlock`, `result_release`, `submission_graded`, `extension_response` | +| `days_before` | Integer | Days before event to send notification | +| `frequency` | Selection | `once`, `daily`, `custom` | +| `custom_intervals` | Text (JSON) | Custom reminder intervals (e.g., [7, 3, 1] days before) | +| `channel` | Selection | `in_app`, `email`, `both` | +| `entity_id` | Many2one | Entity scope | +| `active` | Boolean | Active flag | + +**`encoach.notification.preferences`** + +| Field | Type | Description | +|-------|------|-------------| +| `user_id` | Many2one | User | +| `email_enabled` | Boolean | Receive email notifications | +| `assignment_alerts` | Boolean | Assignment deadline alerts | +| `exam_alerts` | Boolean | Exam alerts | +| `chapter_alerts` | Boolean | Chapter unlock alerts | +| `announcement_alerts` | Boolean | Announcement alerts | +| `message_alerts` | Boolean | New message alerts | + +### 50.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-NOT-01 | In-app notification bell with unread count (existing NotificationDropdown enhanced) | All layouts | All | +| FR-NOT-02 | Email notifications for configured events | Backend | System | +| FR-NOT-03 | Admin configures notification rules (event type, timing, frequency) | `/admin/notification-rules` | Admin | +| FR-NOT-04 | Teacher sets reminder frequency for assignments and exams | Assignment/exam creation forms | Teacher | +| FR-NOT-05 | Students receive deadline alerts, chapter unlock alerts, result release alerts | Dashboard | Student | +| FR-NOT-06 | Users configure personal notification preferences | Profile pages | All | +| FR-NOT-07 | Notification action button redirects to relevant page | All layouts | All | + +### 50.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/notifications` | List notifications (paginated, filter: type, is_read) | +| `POST` | `/api/notifications/{id}/read` | Mark as read | +| `POST` | `/api/notifications/read-all` | Mark all as read | +| `GET` | `/api/notifications/unread-count` | Get unread count | +| `GET` | `/api/notification-rules` | List rules | +| `POST` | `/api/notification-rules` | Create rule | +| `PATCH` | `/api/notification-rules/{id}` | Update rule | +| `DELETE` | `/api/notification-rules/{id}` | Delete rule | +| `GET` | `/api/notification-preferences` | Get user preferences | +| `PATCH` | `/api/notification-preferences` | Update user preferences | + +--- + +## 51. FAQ System + +> **Implementation:** `faq.service.ts` | `encoach_lms_api/controllers/faq.py` | `AdminFAQ.tsx`, `FAQ.tsx` (public) + +### 51.1 Overview + +Interactive FAQ system editable by super admin. FAQ items are organized by categories and filtered by target audience (student, entity, or both). Supports text, images, and video content. + +### 51.2 Data Models + +**`encoach.faq.category`** + +| Field | Type | Description | +|-------|------|-------------| +| `name` | Char | Category name | +| `sequence` | Integer | Display order | +| `icon` | Char | Icon identifier | +| `audience` | Selection | `student`, `entity`, `both` | +| `active` | Boolean | Active flag | + +**`encoach.faq.item`** + +| Field | Type | Description | +|-------|------|-------------| +| `question` | Char | Question text | +| `answer` | Text | Answer (supports markdown, embedded images/video) | +| `category_id` | Many2one | Parent category | +| `audience` | Selection | `student`, `entity`, `both` | +| `image` | Binary | Optional image | +| `video_url` | Char | Optional video URL | +| `sequence` | Integer | Display order | +| `active` | Boolean | Active flag | + +### 51.3 Functional Requirements + +| ID | Requirement | Route | Role | +|----|-------------|-------|------| +| FR-FAQ-01 | Super admin manages FAQ categories and items | `/admin/faq` | Admin | +| FR-FAQ-02 | Admin adds text, images, and video to FAQ answers | `/admin/faq` | Admin | +| FR-FAQ-03 | Admin sets audience filter per category/item (student, entity, both) | `/admin/faq` | Admin | +| FR-FAQ-04 | Students and entity users view FAQs filtered by their role | `/faq` | All | +| FR-FAQ-05 | Search bar to find FAQ items by keyword | `/faq` | All | +| FR-FAQ-06 | Interactive accordion-style display (click question to expand answer) | `/faq` | All | + +### 51.4 API Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/faq/categories` | List categories (filter: audience) | +| `POST` | `/api/faq/categories` | Create category | +| `PATCH` | `/api/faq/categories/{id}` | Update category | +| `DELETE` | `/api/faq/categories/{id}` | Delete category | +| `GET` | `/api/faq/items` | List items (filter: category_id, audience, search) | +| `POST` | `/api/faq/items` | Create item | +| `PATCH` | `/api/faq/items/{id}` | Update item | +| `DELETE` | `/api/faq/items/{id}` | Delete item | + +--- + +# Part XII -- Technical Specifications + +## 52. Data Models + +### 52.1 Existing Models (from `ielts-be-v0`) + +| Model | Module | Purpose | +|-------|--------|---------| +| `res.users` (extended) | `encoach_core` | User accounts with EnCoach fields | +| `encoach.entity` | `encoach_core` | Tenant organizations | +| `encoach.role` | `encoach_core` | Entity roles | +| `encoach.permission` | `encoach_core` | Role permissions | +| `encoach.code` | `encoach_core` | Registration codes | +| `encoach.invite` | `encoach_core` | User invitations | +| `encoach.exam` | `encoach_exam` | Exam definitions (extended with `subject_id`, `topic_ids`) | +| `encoach.approval.workflow` | `encoach_exam` | Exam approval workflows | +| `encoach.assignment` | `encoach_assignment` | Exam assignments | +| `encoach.group` | `encoach_classroom` | Classroom groups | +| `encoach.session` | `encoach_stats` | Exam session state | +| `encoach.stat` | `encoach_stats` | Per-exercise statistics (extended with `topic_id`, `subject_id`) | +| `encoach.evaluation` | `encoach_evaluation` | Writing/speaking evaluation results | +| `encoach.ai.job` | `encoach_evaluation` | Background AI job tracking | +| `encoach.training` | `encoach_training` | Training content records | +| `encoach.training.tip` | `encoach_training` | Training tips with FAISS embeddings | +| `encoach.walkthrough` | `encoach_training` | Module walkthroughs | +| `encoach.package` | `encoach_subscription` | Subscription packages | +| `encoach.subscription.payment` | `encoach_subscription` | Payment records | +| `encoach.discount` | `encoach_subscription` | Discount codes | +| `encoach.ticket` | `encoach_ticket` | Support tickets | +| `encoach.elai.avatar` | `encoach_ai_media` | ELAI avatar profiles | +| `encoach.registration` | `encoach_registration` | Batch registration mixin | + +### 52.2 New Models (Adaptive Learning Engine) + +| Model | Module | Purpose | Key Fields | +|-------|--------|---------|------------| +| `encoach.subject` | `encoach_taxonomy` | Top-level subjects | `name`, `code`, `is_active`, `diagnostic_config` (JSON), `mastery_threshold`, `grading_scale`, `grading_scale_config` (JSON) | +| `encoach.domain` | `encoach_taxonomy` | Subject domains | `name`, `code`, `subject_id`, `sequence` | +| `encoach.topic` | `encoach_taxonomy` | Topics with prerequisites | `name`, `code`, `domain_id`, `estimated_hours`, `difficulty_level`, `prerequisite_ids` (M2M self-ref), `question_type_weights` (JSON) | +| `encoach.learning.objective` | `encoach_taxonomy` | Measurable objectives | `name`, `topic_id`, `bloom_level`, `sequence` | +| `encoach.resource` | `encoach_resources` | Human-uploaded materials | `name`, `resource_type`, `file`/`url`, `topic_ids` (M2M), `author_id`, `is_published`, `review_status` | +| `encoach.proficiency` | `encoach_adaptive` | Per-student per-topic mastery | `student_id`, `topic_id`, `mastery` (float 0-100), `mastery_level`, `last_assessed`, `time_spent_minutes` | +| `encoach.learning.plan` | `encoach_adaptive` | Personalized study plan | `student_id`, `subject_id`, `status`, `ai_summary`, `overall_progress`, `target_completion` | +| `encoach.learning.plan.item` | `encoach_adaptive` | Plan items | `plan_id`, `topic_id`, `sequence`, `status` (locked/available/in_progress/completed), `estimated_hours`, `actual_hours` | +| `encoach.resource.completion` | `encoach_adaptive` | Resource viewing tracking | `student_id`, `resource_id`, `viewed`, `time_spent_minutes`, `rating` | +| `encoach.ai.content.cache` | `encoach_adaptive` | Cached AI-generated content | `topic_id`, `content_type`, `difficulty_level`, `content`, `model_used`, `review_status` | + +### 52.3 New Models (SIS Integration) + +| Model | Module | Purpose | +|-------|--------|---------| +| `encoach.sis.sync` | `encoach_sis` | SIS sync job tracking | +| `encoach.sis.mapping` | `encoach_sis` | Field mapping between SIS and EnCoach | + +### 52.4 New Models (Branding) + +| Model | Module | Purpose | +|-------|--------|---------| +| `encoach.branding` | `encoach_branding` | Tenant branding configuration (logo, colors, fonts) | + +### 52.5 New Models (OpenEduCat Enterprise -- Beyond SRS) + +| Model | Module | Purpose | Key Fields | +|-------|--------|---------|------------| +| `op.student.leave.request` | `openeducat_student_leave_enterprise` | Student leave requests | `request_number`, `student_id`, `leave_type`, `start_date`, `end_date`, `duration`, `description`, `state`, `approve_date` | +| `op.student.leave.type` | `openeducat_student_leave_enterprise` | Leave type definitions | `name` | +| `op.fees.plan` | `openeducat_fees` | Student fee plans | `student_id`, `course_id`, `total_amount`, `paid_amount`, `remaining_amount`, `state` | +| `op.student.fees.details` | `openeducat_fees` | Fee payment details | `student_id`, `amount`, `date`, `state`, `invoice_state`, `product_name` | +| `op.fees.terms` | `openeducat_fees` | Fee payment terms | `name`, `no_days`, `line_ids` | +| `op.session.lesson` | `openeducat_lesson` | Lesson sessions | `name`, `lesson_topic`, `course_id`, `batch_id`, `subject_id`, `session_id`, `faculty_id`, `start_datetime`, `end_datetime` | +| `op.gradebook` | `openeducat_grading` | Student gradebooks | `student_id`, `course_id`, `academic_year_id`, `line_ids` | +| `op.gradebook.line` | `openeducat_grading` | Gradebook entries | `gradebook_id`, `marks`, `percentage`, `state` | +| `op.student.progression` | `openeducat_student_progress_enterprise` | Aggregate progress tracking | `student_id`, `total_attendance`, `total_assignment`, `total_marksheet_line` | +| `op.media` | `openeducat_library` | Library media catalog | `name`, `isbn`, `author`, `edition`, `media_type` | +| `op.media.movement` | `openeducat_library` | Library circulation | `media_id`, `student_id`, `faculty_id`, `issued_date`, `return_date`, `state` | +| `op.library.card` | `openeducat_library` | Library cards | `number`, `student_id`, `faculty_id` | +| `op.activity` | `openeducat_activity` | Student activities | `student_id`, `type_id`, `date`, `description` | +| `op.activity.type` | `openeducat_activity` | Activity type definitions | `name` | +| `op.facility` | `openeducat_facility` | Institutional facilities | `name`, `code` | +| `op.facility.line` | `openeducat_facility` | Facility assets | `name`, `code`, `product_name` | + +### 52.6 Frontend Type Definitions (29 files) + +The frontend defines TypeScript interfaces matching all backend models: + +| Type File | Key Interfaces | +|-----------|---------------| +| `common.ts` | `PaginatedResponse`, `ApiResponse`, `PaginationParams` | +| `auth.ts` | `User`, `UserRole`, `LoginRequest`, `LoginResponse` | +| `entity.ts` | `Entity`, `EntityRole`, `RolePermission` | +| `exam.ts` | `Exam`, `Rubric`, `ExamStructure` | +| `assignment.ts` | `Assignment`, `AssignmentCreateRequest` | +| `classroom.ts` | `Classroom`, `ClassroomMember` | +| `stats.ts` | `ExamSession`, `Stat`, `Evaluation` | +| `subscription.ts` | `Package`, `Payment`, `Discount` | +| `ticket.ts` | `Ticket` | +| `training.ts` | `Training`, `Tip`, `Walkthrough` | +| `taxonomy.ts` | `Subject`, `Domain`, `Topic`, `LearningObjective`, `TaxonomyTree` | +| `adaptive.ts` | `Proficiency`, `LearningPlan`, `DiagnosticSession`, `TopicContent` | +| `lms.ts` | `Course`, `Batch`, `Timetable`, `Attendance`, `Grade` | +| `ai.ts` | `Chat`, `Insight`, `Alert`, `AiGeneration`, `AiGrading` | +| `academic.ts` | `AcademicYear`, `Term`, `Department` | +| `admission.ts` | `Register`, `Admission` | +| `institutional-exam.ts` | `ExamSession`, `Marksheet`, `Submission` | +| `courseware.ts` | `Chapter`, `Material`, `Workbench` | +| `communication.ts` | `DiscussionBoard`, `Post`, `Announcement`, `Message` | +| `notification.ts` | `Notification`, `NotificationRule`, `Preferences` | +| `faq.ts` | `FaqCategory`, `FaqItem` | +| `student-leave.ts` | `StudentLeaveRequest`, `StudentLeaveType` | +| `fees.ts` | `FeesPlan`, `StudentFeesDetail`, `FeesTerms` | +| `lesson.ts` | `Lesson`, `LessonCreateRequest` | +| `gradebook.ts` | `Gradebook`, `GradebookLine`, `GradingAssignment` | +| `student-progress.ts` | `StudentProgression` | +| `library.ts` | `MediaItem`, `MediaMovement`, `LibraryCard` | +| `activity.ts` | `Activity`, `ActivityType` | +| `facility.ts` | `Facility`, `Asset` | + +--- + +## 53. REST API Specification + +### 53.1 Existing Endpoints (81+) + +All existing endpoints from the Odoo 19 backend remain. Key groups: + +| Group | Endpoints | Count | +|-------|-----------|-------| +| Auth | `/api/login`, `/api/logout`, `/api/reset`, `/api/reset/sendVerification` | 4 | +| Users | `/api/user`, `/api/users/update`, `/api/users/list`, `/api/users/{id}` | 6 | +| Entities & Roles | `/api/entities`, `/api/roles`, `/api/permissions` | 7 | +| Exams | `/api/exam`, `/api/exam/{module}`, `/api/exam/{module}/{id}`, `/api/exam/avatars` | 7 | +| AI Generation | `/api/exam/reading/*`, `/api/exam/listening/*`, `/api/exam/writing/*`, `/api/exam/speaking/*`, `/api/exam/level/*` | 12 | +| Media | `/api/exam/listening/media`, `/api/exam/speaking/media`, `/api/transcribe` | 6 | +| Evaluations | `/api/evaluate/writing`, `/api/evaluate/speaking`, `/api/grading/multiple` | 6 | +| Classrooms | `/api/groups` | 3 | +| Assignments | `/api/assignments` | 8 | +| Sessions & Stats | `/api/sessions`, `/api/stats`, `/api/statistical` | 5 | +| Training | `/api/training`, `/api/training/tips`, `/api/training/walkthrough` | 4 | +| Subscriptions | `/api/packages`, `/api/stripe`, `/api/paypal`, `/api/paymob` + webhooks | 7 | +| Registration | `/api/register`, `/api/code/{code}`, `/api/batch_users` | 4 | +| Tickets | `/api/tickets` | 3 | +| Storage | `/api/storage` | 2 | +| Approvals | `/api/approval-workflows` | 3 | + +### 53.2 New Endpoints (Adaptive Learning Engine, 40+) + +| Group | Method | Path | Description | +|-------|--------|------|-------------| +| **Taxonomy** | `GET` | `/api/subjects` | List subjects | +| | `GET` | `/api/subjects/{id}` | Get subject detail | +| | `POST` | `/api/subjects` | Create subject | +| | `PATCH` | `/api/subjects/{id}` | Update subject | +| | `DELETE` | `/api/subjects/{id}` | Delete subject | +| | `GET` | `/api/subjects/{id}/taxonomy` | Full taxonomy tree | +| | `POST` | `/api/subjects/{id}/taxonomy/import` | Bulk import | +| | `GET/POST/PATCH/DELETE` | `/api/domains`, `/api/topics` | Domain and topic CRUD | +| **Resources** | `GET` | `/api/resources` | List (filter by topic, type) | +| | `POST` | `/api/resources` | Upload resource (multipart) | +| | `PATCH` | `/api/resources/{id}` | Update metadata | +| | `DELETE` | `/api/resources/{id}` | Delete | +| | `GET` | `/api/resources/{id}/download` | Download file | +| | `POST` | `/api/resources/{id}/complete` | Mark viewed | +| | `POST` | `/api/resources/{id}/rate` | Rate (1-5) | +| **Diagnostic** | `POST` | `/api/diagnostic/start` | Start adaptive diagnostic | +| | `POST` | `/api/diagnostic/answer` | Submit answer, get next question | +| | `GET` | `/api/diagnostic/{id}/result` | Get diagnostic results | +| **Proficiency** | `GET` | `/api/proficiency` | Student's profile (by subject) | +| | `GET` | `/api/proficiency/summary` | Cross-subject summary | +| | `GET` | `/api/proficiency/class` | Class-level (teacher/admin) | +| **Learning Plan** | `GET` | `/api/learning-plan` | Active plan (by subject) | +| | `POST` | `/api/learning-plan/generate` | Generate/regenerate | +| | `PATCH` | `/api/learning-plan/{id}` | Teacher override | +| | `POST` | `/api/learning-plan/{id}/pause` | Pause plan | +| | `POST` | `/api/learning-plan/{id}/resume` | Resume plan | +| **Content** | `GET` | `/api/topics/{id}/content` | Get learning content (hybrid) | +| | `POST` | `/api/topics/{id}/generate-content` | Force AI generation | +| | `POST` | `/api/topics/{id}/practice` | Generate practice questions | +| | `POST` | `/api/topics/{id}/practice/grade` | Grade practice answers | +| | `POST` | `/api/topics/{id}/mastery-quiz` | Start mastery quiz | +| | `POST` | `/api/topics/{id}/mastery-quiz/submit` | Submit mastery quiz | +| **AI Coaching** | `POST` | `/api/coach/chat` | AI assistant conversation | +| | `POST` | `/api/coach/hint` | Request hint | +| | `POST` | `/api/coach/explain` | Request explanation | +| | `POST` | `/api/coach/suggest` | Study suggestions | +| | `POST` | `/api/coach/writing-help` | Writing assistance | +| | `GET` | `/api/coach/tip` | Contextual tip | +| **AI Utilities** | `POST` | `/api/ai/search` | Semantic search | +| | `POST` | `/api/ai/insights` | Data insights | +| | `GET` | `/api/ai/alerts` | Risk alerts | +| | `POST` | `/api/ai/report-narrative` | Report narrative | +| | `POST` | `/api/ai/batch-optimize` | Batch optimization | +| **Analytics** | `GET` | `/api/analytics/student` | Student analytics | +| | `GET` | `/api/analytics/class` | Class analytics | +| | `GET` | `/api/analytics/subject` | Subject analytics | +| | `GET` | `/api/analytics/content-gaps` | Content gap report | + +### 53.3 New Endpoints (LMS API Bridge) + +| Method | Path | Description | +|--------|------|-------------| +| `GET/POST` | `/api/courses` | List/create courses | +| `GET/PATCH/DELETE` | `/api/courses/{id}` | Course CRUD | +| `POST` | `/api/courses/ai-generate` | AI-generate course outline | +| `GET/POST` | `/api/batches` | List/create batches | +| `GET/PATCH/DELETE` | `/api/batches/{id}` | Batch CRUD | +| `GET/POST` | `/api/timetable` | Timetable sessions | +| `GET/POST` | `/api/attendance` | Attendance records | +| `GET` | `/api/grades` | Gradebook | + +### 53.4 New Endpoints (SIS Integration) + +| Method | Path | Description | +|--------|------|-------------| +| `POST` | `/api/sis/sync` | Trigger SIS sync | +| `GET` | `/api/sis/status` | Sync status | +| `GET` | `/api/sis/mappings` | Field mappings | +| `PATCH` | `/api/sis/mappings` | Update mappings | + +### 53.5 New Endpoints (OpenEduCat Institutional LMS, 60+) + +| Group | Method | Path | Description | +|-------|--------|------|-------------| +| **Academic Years** | `GET/POST` | `/api/academic-years` | List/create years | +| | `GET/PATCH/DELETE` | `/api/academic-years/{id}` | Year CRUD | +| | `POST` | `/api/academic-years/{id}/generate-terms` | Auto-generate terms | +| | `GET/POST` | `/api/academic-terms` | List/create terms | +| | `PATCH/DELETE` | `/api/academic-terms/{id}` | Term CRUD | +| **Departments** | `GET/POST` | `/api/departments` | List/create | +| | `PATCH/DELETE` | `/api/departments/{id}` | CRUD | +| **Admissions** | `GET/POST` | `/api/admission-registers` | List/create registers | +| | `PATCH` | `/api/admission-registers/{id}` | Update | +| | `POST` | `/api/admission-registers/{id}/confirm` | Confirm register | +| | `POST` | `/api/admission-registers/{id}/close` | Close register | +| | `GET/POST` | `/api/admissions` | List/create admissions | +| | `GET` | `/api/admissions/{id}` | Admission detail | +| | `POST` | `/api/admissions/{id}/submit` | Submit for review | +| | `POST` | `/api/admissions/{id}/confirm` | Confirm | +| | `POST` | `/api/admissions/{id}/admit` | Admit (creates student) | +| | `POST` | `/api/admissions/{id}/reject` | Reject | +| **Subject Registration** | `GET/POST` | `/api/subject-registrations` | List/create | +| | `PATCH` | `/api/subject-registrations/{id}` | Update subjects | +| | `POST` | `/api/subject-registrations/{id}/confirm` | Confirm | +| | `POST` | `/api/subject-registrations/{id}/reject` | Reject | +| | `GET` | `/api/subject-registrations/available` | Available subjects | +| **Inst. Exam Sessions** | `GET/POST` | `/api/inst-exam-sessions` | List/create | +| | `GET/PATCH/DELETE` | `/api/inst-exam-sessions/{id}` | CRUD | +| | `POST` | `/api/inst-exam-sessions/{id}/schedule` | Schedule | +| | `POST` | `/api/inst-exam-sessions/{id}/done` | Mark done | +| | `POST` | `/api/inst-exams` | Add exam | +| | `PATCH` | `/api/inst-exams/{id}` | Update exam | +| | `POST` | `/api/inst-exams/{id}/attendees` | Add attendees | +| | `PATCH` | `/api/inst-exams/{id}/marks` | Enter marks | +| | `GET/POST` | `/api/exam-types` | List/create types | +| | `GET/POST` | `/api/grade-config` | Grade configuration | +| | `GET/POST` | `/api/result-templates` | Result templates | +| | `POST` | `/api/result-templates/{id}/generate` | Generate marksheets | +| | `GET` | `/api/marksheets` | List marksheets | +| | `GET` | `/api/marksheets/{id}` | Marksheet detail | +| | `POST` | `/api/marksheets/{id}/validate` | Validate | +| **Course Assignments** | `GET/POST` | `/api/course-assignments` | List/create | +| | `GET/PATCH` | `/api/course-assignments/{id}` | CRUD | +| | `POST` | `/api/course-assignments/{id}/publish` | Publish | +| | `POST` | `/api/course-assignments/{id}/finish` | Close | +| | `GET` | `/api/course-assignments/{id}/submissions` | List submissions | +| | `POST` | `/api/course-assignments/{id}/submit` | Student submits | +| | `PATCH` | `/api/submissions/{id}` | Grade submission | +| | `GET/POST` | `/api/assignment-types` | Assignment types | + +--- + +### 53.6 New Endpoints (Courseware, Communication, Notifications, FAQ, 60+) + +| Group | Method | Path | Description | +|-------|--------|------|-------------| +| **Chapters** | `GET` | `/api/courses/{courseId}/chapters` | List chapters | +| | `POST` | `/api/courses/{courseId}/chapters` | Create chapter | +| | `GET` | `/api/chapters/{id}` | Chapter detail | +| | `PATCH` | `/api/chapters/{id}` | Update chapter | +| | `DELETE` | `/api/chapters/{id}` | Delete chapter | +| | `POST` | `/api/chapters/{id}/unlock` | Unlock chapter | +| | `POST` | `/api/chapters/{id}/lock` | Lock chapter | +| | `PATCH` | `/api/courses/{courseId}/chapters/reorder` | Reorder | +| | `GET` | `/api/chapters/{id}/progress` | Progress | +| | `POST` | `/api/chapters/{id}/progress/complete` | Complete | +| **Materials** | `GET` | `/api/chapters/{chapterId}/materials` | List | +| | `POST` | `/api/chapters/{chapterId}/materials` | Upload | +| | `PATCH` | `/api/materials/{id}` | Update | +| | `DELETE` | `/api/materials/{id}` | Delete | +| | `GET` | `/api/materials/{id}/download` | Download | +| | `POST` | `/api/materials/{id}/viewed` | Mark viewed | +| **Workbench** | `POST` | `/api/workbench/generate-outline` | Generate outline | +| | `POST` | `/api/workbench/generate-chapter` | Generate chapter | +| | `POST` | `/api/workbench/generate-rubric` | Generate rubric | +| | `POST` | `/api/workbench/regenerate` | Regenerate section | +| | `POST` | `/api/workbench/suggest-materials` | Suggest materials | +| | `POST` | `/api/workbench/publish` | Publish content | +| **Discussions** | `GET/POST` | `/api/discussion-boards` | List/create boards | +| | `PATCH` | `/api/discussion-boards/{id}` | Update board | +| | `GET/POST` | `/api/discussion-boards/{id}/posts` | List/create posts | +| | `PATCH/DELETE` | `/api/posts/{id}` | Update/delete post | +| | `POST` | `/api/posts/{id}/pin` | Pin post | +| | `POST` | `/api/posts/{id}/resolve` | Resolve post | +| **Announcements** | `GET/POST` | `/api/announcements` | List/create | +| | `PATCH/DELETE` | `/api/announcements/{id}` | Update/delete | +| | `POST` | `/api/announcements/{id}/publish` | Publish | +| **Messages** | `GET` | `/api/messages` | Inbox | +| | `GET` | `/api/messages/sent` | Sent | +| | `POST` | `/api/messages` | Send | +| | `GET` | `/api/messages/{id}` | Detail | +| | `DELETE` | `/api/messages/{id}` | Delete | +| | `GET` | `/api/messages/unread-count` | Unread count | +| **Notifications** | `GET` | `/api/notifications` | List | +| | `POST` | `/api/notifications/{id}/read` | Mark read | +| | `POST` | `/api/notifications/read-all` | Read all | +| | `GET` | `/api/notifications/unread-count` | Count | +| | `GET/POST` | `/api/notification-rules` | Rules | +| | `PATCH/DELETE` | `/api/notification-rules/{id}` | Rule CRUD | +| | `GET/PATCH` | `/api/notification-preferences` | User prefs | +| **FAQ** | `GET/POST` | `/api/faq/categories` | Categories | +| | `PATCH/DELETE` | `/api/faq/categories/{id}` | Category CRUD | +| | `GET/POST` | `/api/faq/items` | Items | +| | `PATCH/DELETE` | `/api/faq/items/{id}` | Item CRUD | +| **Plagiarism** | `POST` | `/api/plagiarism/check` | Check text | +| | `GET` | `/api/plagiarism/report/{submissionId}` | Get report | +| | `GET` | `/api/plagiarism/report/{submissionId}/download` | Download PDF | +| **Exam Access** | `POST` | `/api/exam/{id}/generate-link` | Generate access link | +| | `GET` | `/api/exam/access/{token}` | Access via link | +| | `POST` | `/api/exam/official-login` | Official exam login | + +### 53.7 New Endpoints (OpenEduCat Enterprise Features, 40+) + +| Group | Method | Path | Description | +|-------|--------|------|-------------| +| **Student Leave** | `GET` | `/api/student-leaves` | List leave requests | +| | `POST` | `/api/student-leaves` | Create leave request | +| | `PATCH` | `/api/student-leaves/{id}` | Update leave | +| | `POST` | `/api/student-leaves/{id}/approve` | Approve | +| | `POST` | `/api/student-leaves/{id}/reject` | Reject | +| | `GET/POST` | `/api/student-leave-types` | Leave types | +| **Fees** | `GET` | `/api/fees-plans` | List fee plans | +| | `GET` | `/api/fees-plans/{id}` | Fee plan detail | +| | `GET` | `/api/student-fees` | Student fee details | +| | `GET` | `/api/fees-terms` | Fee terms | +| **Lessons** | `GET/POST` | `/api/lessons` | List/create lessons | +| | `PATCH/DELETE` | `/api/lessons/{id}` | Update/delete | +| **Gradebook** | `GET` | `/api/gradebooks` | List gradebooks | +| | `GET` | `/api/gradebook-lines` | Gradebook lines | +| | `GET/POST` | `/api/grading-assignments` | Grading assignments | +| | `PATCH/DELETE` | `/api/grading-assignments/{id}` | CRUD | +| **Student Progress** | `GET` | `/api/student-progress` | Progression records | +| **Library** | `GET/POST` | `/api/library/media` | Media items | +| | `DELETE` | `/api/library/media/{id}` | Delete media | +| | `GET/POST` | `/api/library/movements` | Movements | +| | `PATCH` | `/api/library/movements/{id}` | Update movement | +| | `POST` | `/api/library/movements/{id}/return` | Return media | +| | `GET/POST` | `/api/library/cards` | Library cards | +| **Activities** | `GET/POST` | `/api/activities` | Activities | +| | `PATCH/DELETE` | `/api/activities/{id}` | CRUD | +| | `GET/POST` | `/api/activity-types` | Activity types | +| | `DELETE` | `/api/activity-types/{id}` | Delete type | +| **Facilities** | `GET/POST` | `/api/facilities` | Facilities | +| | `PATCH/DELETE` | `/api/facilities/{id}` | CRUD | +| | `GET/POST` | `/api/assets` | Assets | +| | `DELETE` | `/api/assets/{id}` | Delete asset | +| **Roles** | `GET/POST` | `/api/roles` | Roles | +| | `GET/PATCH/DELETE` | `/api/roles/{id}` | Role CRUD | +| | `PATCH` | `/api/roles/{id}/permissions` | Update permissions | +| | `GET/POST` | `/api/permissions` | Permissions | +| | `DELETE` | `/api/permissions/{id}` | Delete permission | +| | `GET` | `/api/users/with-roles` | Users with roles | +| | `GET/PATCH` | `/api/users/{id}/roles` | User roles | +| | `POST` | `/api/users/{id}/roles/toggle` | Toggle role | +| | `GET` | `/api/authority-matrix` | Authority matrix | +| | `POST` | `/api/authority-matrix/toggle` | Toggle cell | +| | `GET` | `/api/user-authority-matrix` | User authority | + +--- + +## 54. Frontend Page Inventory + +### 54.1 Auth Pages (3) + +| Route | Page | API Dependencies | +|-------|------|-----------------| +| `/login` | Login | `POST /api/login` | +| `/register` | Register | `POST /api/register` | +| `/forgot-password` | Forgot Password | `POST /api/reset/sendVerification` | + +### 54.2 Student Pages (18+) + +| Route | Page | Key APIs | AI Components | +|-------|------|----------|---------------| +| `/student/dashboard` | Student Dashboard | `/api/user`, `/api/proficiency/summary`, `/api/learning-plan` | AiStudyCoach, AiTipBanner | +| `/student/subjects` | **NEW:** Subject Selection | `/api/subjects`, `/api/proficiency/summary` | -- | +| `/student/diagnostic/:subjectId` | **NEW:** Diagnostic Test | `/api/diagnostic/start`, `/api/diagnostic/answer` | -- | +| `/student/proficiency/:subjectId` | **NEW:** Proficiency Profile | `/api/proficiency?subjectId=` | -- | +| `/student/plan/:subjectId` | **NEW:** Learning Plan | `/api/learning-plan?subjectId=` | AiStudyCoach | +| `/student/topic/:topicId` | **NEW:** Topic Learning | `/api/topics/{id}/content`, `/api/resources` | AiCoach (hints, explanations) | +| `/student/courses` | Course List | `/api/courses` | AiTipBanner | +| `/student/courses/:id` | Course Detail | `/api/courses/{id}` | -- | +| `/student/assignments` | Assignments | `/api/assignments` | -- | +| `/student/grades` | Grades | `/api/grades` | AiGradeExplainer | +| `/student/attendance` | Attendance | `/api/attendance` | -- | +| `/student/timetable` | Timetable | `/api/timetable` | -- | +| `/student/profile` | Profile | `/api/user` | -- | +| `/student/subject-registration` | **NEW:** Subject Registration | `/api/subject-registrations/available`, `/api/subject-registrations` | -- | +| `/student/courses/:id/chapters/:chapterId` | **NEW:** Chapter View | `/api/chapters/{id}`, `/api/chapters/{chapterId}/materials` | -- | +| `/student/discussions` | **NEW:** Discussion Board | `/api/discussion-boards`, `/api/discussion-boards/{id}/posts` | -- | +| `/student/announcements` | **NEW:** Announcements | `/api/announcements` | -- | +| `/student/messages` | **NEW:** Messages | `/api/messages`, `/api/messages/unread-count` | -- | +| `/student/journey` | **NEW:** Student Journey | `/api/analytics/student`, `/api/proficiency` | -- | + +### 54.3 Teacher Pages (15+) + +| Route | Page | Key APIs | AI Components | +|-------|------|----------|---------------| +| `/teacher/dashboard` | Teacher Dashboard | `/api/user`, `/api/analytics/class` | AiInsightsPanel, AiAlertBanner | +| `/teacher/courses` | Courses | `/api/courses` | -- | +| `/teacher/courses/new` | Course Builder | `/api/courses`, `/api/subjects/{id}/taxonomy` | AiCreationAssistant | +| `/teacher/courses/:id/edit` | Edit Course | `/api/courses/{id}` | AiCreationAssistant | +| `/teacher/assignments` | Assignments | `/api/assignments` | AiCreationAssistant | +| `/teacher/assignments/:id` | Assignment Detail / Grading | `/api/assignments/{id}`, `/api/evaluate/*` | AiGradingAssistant | +| `/teacher/attendance` | Attendance | `/api/attendance` | AiRiskBadge | +| `/teacher/students` | Students | `/api/users/list?type=student` | AiRiskBadge | +| `/teacher/timetable` | Timetable | `/api/timetable` | -- | +| `/teacher/profile` | Profile | `/api/user` | -- | +| `/teacher/courses/:id/chapters` | **NEW:** Course Chapters | `/api/courses/{courseId}/chapters` | -- | +| `/teacher/courses/:id/chapters/:chapterId` | **NEW:** Chapter Detail | `/api/chapters/{id}`, `/api/chapters/{chapterId}/materials` | -- | +| `/teacher/courses/:id/workbench` | **NEW:** AI Workbench | `/api/workbench/*` | AiCreationAssistant | +| `/teacher/courses/:id/discussions` | **NEW:** Discussion Board | `/api/discussion-boards`, `/api/discussion-boards/{id}/posts` | -- | +| `/teacher/announcements` | **NEW:** Announcements | `/api/announcements` | -- | + +### 54.4 Public Pages (4+) + +| Route | Page | Key APIs | AI Components | +|-------|------|----------|---------------| +| `/apply` | **NEW:** Admission Application | `/api/admissions`, `/api/admission-registers` | -- | +| `/apply/status` | **NEW:** Application Status | `/api/admissions/{id}` | -- | +| `/exam/access/{token}` | **NEW:** Official Exam Access (Link) | `/api/exam/access/{token}` | -- | +| `/exam/official/{code}` | **NEW:** Official Exam Access (Landing) | `/api/exam/official-login` | -- | +| `/exam/login/{examId}` | **NEW:** Official Exam Login | `/api/exam/official-login` | -- | +| `/faq` | **NEW:** FAQ | `/api/faq/categories`, `/api/faq/items` | -- | + +### 54.5 Admin Pages (53 -- Verified) + +| Route | Page | Key APIs | AI Components | +|-------|------|----------|---------------| +| `/admin/dashboard` | LMS Dashboard | `/api/analytics/subject`, `/api/courses` | AiInsightsPanel, AiAlertBanner | +| `/admin/platform` | Platform Dashboard | `/api/users/list`, entity counts | AiInsightsPanel | +| `/admin/courses` | Course Management | `/api/courses` | AiCreationAssistant | +| `/admin/students` | Student Management | `/api/users/list?type=student` | AiRiskBadge | +| `/admin/teachers` | Teacher Management | `/api/users/list?type=teacher` | -- | +| `/admin/batches` | Batch Management | `/api/batches` | AiBatchOptimizer | +| `/admin/batches/:id` | Batch Detail | `/api/batches/{id}` | AiBatchOptimizer | +| `/admin/timetable` | Timetable Admin | `/api/timetable` | -- | +| `/admin/reports` | Reports / Analytics | `/api/analytics/*` | AiReportNarrative | +| `/admin/settings` | LMS Settings | Configuration APIs | -- | +| `/admin/assignments` | Assignments | `/api/assignments` | AiCreationAssistant | +| `/admin/examsList` | Exams List + Rubrics | `/api/exam` | -- | +| `/admin/exam-structures` | Exam Structures | `/api/exam-structures` | -- | +| `/admin/rubrics` | Rubrics | `/api/rubrics` | AiCreationAssistant | +| `/admin/generation` | Exam Generation | `/api/exam/*/generate` | AiGeneratorModal | +| `/admin/approval-workflows` | Approval Workflows | `/api/approval-workflows` | AiGradingAssistant | +| `/admin/users` | User Management | `/api/users/list` | -- | +| `/admin/entities` | Entity Management | `/api/entities` | -- | +| `/admin/classrooms` | Classroom Management | `/api/groups` | -- | +| `/admin/taxonomy` | Taxonomy Manager | `/api/subjects`, `/api/domains`, `/api/topics` | -- | +| `/admin/resources` | Resource Manager | `/api/resources`, `/api/analytics/content-gaps` | -- | +| `/admin/adaptive-analytics` | Adaptive Analytics | `/api/analytics/subject`, `/api/analytics/content-gaps` | AiInsightsPanel | +| `/admin/student-performance` | Student Performance | `/api/proficiency/class` | AiStudyCoach, AiGradeExplainer | +| `/admin/stats-corporate` | Corporate Stats | `/api/statistical` | -- | +| `/admin/record` | Record | `/api/stats` | -- | +| `/admin/training/vocabulary` | Vocabulary | `/api/training`, FAISS tips | -- | +| `/admin/training/grammar` | Grammar | `/api/training`, FAISS tips | -- | +| `/admin/payment-record` | Payment Record | `/api/packages`, payment APIs | -- | +| `/admin/tickets` | Tickets | `/api/tickets` | -- | +| `/admin/settings-platform` | Platform Settings | Settings APIs | -- | +| `/admin/exam` | Exam Runner | `/api/exam`, `/api/sessions` | -- | +| `/admin/profile` | Admin Profile | `/api/user` | -- | +| `/admin/academic-years` | Academic Year Manager | `/api/academic-years`, `/api/academic-terms` | -- | +| `/admin/departments` | Department Manager | `/api/departments` | -- | +| `/admin/admissions` | Admission List | `/api/admissions` | -- | +| `/admin/admissions/:id` | Admission Detail | `/api/admissions/{id}` | -- | +| `/admin/admission-register` | Admission Register | `/api/admission-registers` | -- | +| `/admin/exam-sessions` | Institutional Exam Sessions | `/api/inst-exam-sessions`, `/api/inst-exams` | -- | +| `/admin/marksheets` | Marksheet Manager | `/api/marksheets`, `/api/result-templates`, `/api/grade-config` | -- | +| `/admin/faq` | FAQ Manager | `/api/faq/categories`, `/api/faq/items` | -- | +| `/admin/notification-rules` | Notification Rules | `/api/notification-rules` | -- | +| `/admin/approval-config` | Approval Workflow Config | `/api/approval-workflows` | -- | +| `/admin/student-leave` | **BEYOND SRS:** Student Leave Management | `/api/student-leaves`, `/api/student-leave-types` | -- | +| `/admin/fees` | **BEYOND SRS:** Fees Management | `/api/fees-plans`, `/api/student-fees`, `/api/fees-terms` | -- | +| `/admin/lessons` | **BEYOND SRS:** Lessons Management | `/api/lessons` | -- | +| `/admin/gradebook` | **BEYOND SRS:** Gradebook | `/api/gradebooks`, `/api/gradebook-lines`, `/api/grading-assignments` | -- | +| `/admin/student-progress` | **BEYOND SRS:** Student Progress | `/api/student-progress` | -- | +| `/admin/library` | **BEYOND SRS:** Library Management | `/api/library/media`, `/api/library/movements`, `/api/library/cards` | -- | +| `/admin/activities` | **BEYOND SRS:** Activity Management | `/api/activities`, `/api/activity-types` | -- | +| `/admin/facilities` | **BEYOND SRS:** Facility Management | `/api/facilities`, `/api/assets` | -- | +| `/admin/roles-permissions` | **BEYOND SRS:** Roles & Permissions CRUD | `/api/roles`, `/api/permissions` | -- | +| `/admin/user-roles` | **BEYOND SRS:** User Role Assignment | `/api/users/with-roles` | -- | +| `/admin/authority-matrix` | **BEYOND SRS:** Authority Matrix | `/api/authority-matrix` | -- | + +--- + +## 55. Non-Functional Requirements + +| ID | Requirement | +|----|-------------| +| NFR-SEC-01 | Authorize on server/API; do not rely on hiding UI alone | +| NFR-SEC-02 | Students can only access their own proficiency and learning plan data | +| NFR-SEC-03 | AI prompts never include student personal data | +| NFR-SEC-04 | Resource uploads validated for file type (no executables) | +| NFR-PERF-01 | Pagination and server-side filtering for all list views | +| NFR-PERF-02 | Diagnostic question generation < 3 seconds | +| NFR-PERF-03 | AI grading response < 10 seconds (writing/speaking < 60 seconds) | +| NFR-PERF-04 | Learning plan generation < 10 seconds | +| NFR-PERF-05 | AI content generation < 15 seconds | +| NFR-PERF-06 | API response time < 2 seconds for standard CRUD | +| NFR-SCALE-01 | 200 concurrent students per subject | +| NFR-SCALE-02 | 500 topics per subject | +| NFR-SCALE-03 | 1,000 resources per subject | +| NFR-UX-01 | Consistent search/filter/pagination patterns; empty states; loading feedback | +| NFR-UX-02 | Math content rendered with KaTeX; IT code rendered with syntax highlighting | +| NFR-A11Y-01 | Icon-only actions have accessible names | +| NFR-A11Y-02 | All forms have proper labels and validation messages | +| NFR-DATA-01 | Proficiency scores use weighted averages (never direct overwrite) | +| NFR-DATA-02 | Learning plan changes are logged with user ID and timestamp | +| NFR-DATA-03 | Resource deletions are soft-delete to preserve completion records | + +--- + +## Appendix A: Odoo Module Inventory (Verified Against Backend v2) + +The following module inventory reflects the actual deployed modules in `encoach_backend_new_v2`: + +**Custom EnCoach Modules (27):** + +| # | Module | Status | Description | +|---|--------|--------|-------------| +| 1 | `encoach_core` | Deployed | Users, entities, roles, permissions, codes, invites | +| 2 | `encoach_ai` | Deployed | OpenAI service, constants, blacklist, token counting | +| 3 | `encoach_ai_media` | Deployed | TTS (Polly), STT (Whisper), ELAI avatars | +| 4 | `encoach_ai_generation` | Deployed | Exam content generation (multi-subject) | +| 5 | `encoach_ai_grading` | Deployed | Writing/speaking grading (multi-subject rubrics) | +| 6 | `encoach_exam` | Deployed | Exam model with `subject_id`, `topic_ids` | +| 7 | `encoach_assignment` | Deployed | Exam assignments | +| 8 | `encoach_classroom` | Deployed | Classroom groups | +| 9 | `encoach_stats` | Deployed | Sessions and statistics with `topic_id`, `subject_id` | +| 10 | `encoach_training` | Deployed | Training tips and walkthroughs | +| 11 | `encoach_subscription` | Deployed | Packages, payments, discounts | +| 12 | `encoach_registration` | Deployed | User registration and batch import | +| 13 | `encoach_ticket` | Deployed | Support tickets | +| 14 | `encoach_api` | Deployed | REST API controllers (~120 routes: auth, users, entities, roles, exams, assignments, classrooms, storage, stats, subscriptions, tickets, approvals, training, generation, AI analytics) | +| 15 | `encoach_taxonomy` | Deployed | Subject, domain, topic, learning objective models | +| 16 | `encoach_resources` | Deployed | Learning resource library (~7 routes) | +| 17 | `encoach_adaptive` | Deployed | Proficiency, learning plans, progress tracking, content cache | +| 18 | `encoach_adaptive_api` | Deployed | REST controllers for adaptive learning (~41 routes: taxonomy, diagnostic, proficiency, learning plans, content, coaching) | +| 19 | `encoach_adaptive_ai` | Deployed | AI services for diagnostics, plans, coaching, content | +| 20 | `encoach_lms_api` | Deployed | REST API bridge for OpenEduCat + enterprise models (~209 routes) | +| 21 | `encoach_sis` | Deployed | UTAS SIS integration (sync, mapping) | +| 22 | `encoach_branding` | Deployed | Whitelabeling configuration | +| 23 | `encoach_courseware` | Deployed | Course chapters, chapter materials, chapter progress, AI workbench | +| 24 | `encoach_communication` | Deployed | Discussion boards, posts, announcements, messaging | +| 25 | `encoach_notification` | Deployed | Notification engine, notification rules, reminders, preferences | +| 26 | `encoach_faq` | Deployed | FAQ categories and items, role-filtered | +| 27 | `encoach_approval` | Deployed | Approval workflows, stages, requests | + +**OpenEduCat Community Modules (14):** + +| # | Module | Status | Description | +|---|--------|--------|-------------| +| 1 | `openeducat_core` | Deployed | `op.course`, `op.batch`, `op.student`, `op.faculty`, `op.subject`, `op.department`, `op.category`, `op.academic.year`, `op.academic.term`, `op.student.course`, `op.subject.registration` | +| 2 | `openeducat_timetable` | Deployed | `op.session`, `op.timing` | +| 3 | `openeducat_attendance` | Deployed | `op.attendance.register`, `op.attendance.sheet`, `op.attendance.line`, `op.attendance.type` | +| 4 | `openeducat_classroom` | Deployed | `op.classroom` (physical rooms) | +| 5 | `openeducat_exam` | Deployed | `op.exam.session`, `op.exam`, `op.exam.type`, `op.exam.attendees`, `op.exam.room`, `op.marksheet.register`, `op.marksheet.line`, `op.result.line`, `op.result.template`, `op.grade.configuration` | +| 6 | `openeducat_assignment` | Deployed | `op.assignment`, `op.assignment.sub.line`, `grading.assignment`, `grading.assignment.type` | +| 7 | `openeducat_admission` | Deployed | `op.admission`, `op.admission.register` | +| 8 | `openeducat_facility` | Deployed | `op.facility`, `op.facility.line` | +| 9 | `openeducat_fees` | Deployed | `op.fees.plan`, `op.student.fees.details`, `op.fees.terms` | +| 10 | `openeducat_library` | Deployed | `op.media`, `op.media.movement`, `op.library.card` | +| 11 | `openeducat_activity` | Deployed | `op.activity`, `op.activity.type` | +| 12 | `openeducat_parent` | Deployed | Parent-student relationship management | +| 13 | `openeducat_erp` | Deployed | OpenEduCat ERP connector (meta-module) | +| 14 | `theme_web_openeducat` | Deployed | OpenEduCat web theme | + +**Total: 27 custom EnCoach + 14 OpenEduCat = 41 modules** + +--- + +## Appendix B: Implementation Status + +All items have been implemented and deployed to staging. The table below records the original priority assignments. + +| Priority | Components | Status | +|----------|-----------|--------| +| **P0** | Auth, core user management, taxonomy models, resource model | **DONE** | +| **P1** | Diagnostic engine, proficiency profile, learning plan generation | **DONE** | +| **P1** | Exam engine with multi-subject support | **DONE** | +| **P2** | OpenEduCat porting (v17→v19), LMS API bridge, course/batch/timetable/attendance | **DONE** | +| **P2** | Academic years/terms, departments, admission workflow | **DONE** | +| **P2** | Content delivery (hybrid), practice questions, mastery quizzes | **DONE** | +| **P2** | AI components wiring (all 15 frontend components to real backend) | **DONE** | +| **P3** | AI coaching (hints, explanations, study suggestions) | **DONE** | +| **P3** | Spaced repetition, analytics dashboards | **DONE** | +| **P3** | Institutional exam sessions, marksheets, subject registration | **DONE** | +| **P3** | Course assignment submissions (file upload, grading) | **DONE** | +| **P2** | Courseware module (chapters, materials, progress tracking) | **DONE** | +| **P2** | Communication module (discussions, announcements, messaging) | **DONE** | +| **P3** | Notification engine (rules, email integration, reminders) | **DONE** | +| **P3** | Enhanced approval workflows (timed stages, escalation, bypass) | **DONE** | +| **P3** | Plagiarism detection (GPTZero integration) | **DONE** | +| **P3** | Official exam access modes (link, landing page, separate login) | **DONE** | +| **P4** | FAQ system (admin-managed, role-filtered) | **DONE** | +| **P4** | AI Workbench for course content generation | **DONE** | +| **P3** | SIS integration, whitelabeling | **DONE** | +| **P4** | Content gap detection, FAISS tips per subject, batch optimizer | **DONE** | +| **P4** | Payment system, subscription management | **DONE** | +| **--** | **BEYOND SRS:** Student leave management | **DONE** | +| **--** | **BEYOND SRS:** Fees management | **DONE** | +| **--** | **BEYOND SRS:** Lessons management | **DONE** | +| **--** | **BEYOND SRS:** Gradebook and grading assignments | **DONE** | +| **--** | **BEYOND SRS:** Student progress tracking | **DONE** | +| **--** | **BEYOND SRS:** Library management | **DONE** | +| **--** | **BEYOND SRS:** Activity management | **DONE** | +| **--** | **BEYOND SRS:** Facility and asset management | **DONE** | +| **--** | **BEYOND SRS:** Roles CRUD, user role assignment, authority matrix | **DONE** | + +## Appendix C: API Route Summary (Verified) + +| Controller Package | Route Count | Scope | +|-------------------|-------------|-------| +| `encoach_api` | ~120 | Auth, users, entities, roles, exams, assignments, classrooms, storage, stats, subscriptions, tickets, approvals, training, generation, AI analytics | +| `encoach_lms_api` | ~209 | Courses, students, teachers, batches, timetable, attendance, grades, departments, academic, admissions, subject registration, institutional exams, course assignments, student leave, fees, lessons, gradebook, student progress, library, activities, facilities, notifications, FAQ, courseware, plagiarism, communication, classrooms | +| `encoach_adaptive_api` | ~41 | Taxonomy (subjects, domains, topics), diagnostic, proficiency, learning plans, content, coaching | +| `encoach_resources` | ~7 | Learning resources (CRUD, download, complete, rate) | +| **Total** | **~377** | | + +## Appendix D: Frontend File Summary (Verified) + +| Category | Count | Location | +|----------|-------|----------| +| **Root pages** | 28 | `src/pages/*.tsx` | +| **Admin pages** | 33 | `src/pages/admin/*.tsx` | +| **Student pages** | 19 | `src/pages/student/*.tsx` | +| **Teacher pages** | 14 | `src/pages/teacher/*.tsx` | +| **Total pages** | **93** | | +| **Service modules** | 37 | `src/services/*.service.ts` | +| **Type definition files** | 29 | `src/types/*.ts` | +| **Query hook modules** | 21 | `src/hooks/queries/use*.ts` | +| **AI components** | 14 | `src/components/ai/*.tsx` | + +--- + +*This is the definitive SRS for the new EnCoach platform. All previous SRS documents (`SRS-EnCoach.md`, `MATH_IT_ADAPTIVE_LEARNING_SRS.md`, `ODOO_MIGRATION_SRS_v2.md`, `ENCOACH_UNIFIED_SRS.md` v1.0) are superseded by this document for new development.* diff --git a/docs/ODOO_DEVELOPER_HANDOFF.md b/docs/ODOO_DEVELOPER_HANDOFF.md new file mode 100644 index 00000000..06515860 --- /dev/null +++ b/docs/ODOO_DEVELOPER_HANDOFF.md @@ -0,0 +1,100 @@ +# Odoo Developer Handoff — Implementation Complete + +**Status:** All deliverables implemented and deployed to staging. +**Date:** March 11, 2026 + +--- + +## 1. Current Repositories + +| Repository | URL | Description | +|-----------|-----|-------------| +| **Frontend v2** | `https://git.albousalh.com/devops/encoach_frontend_new_v2.git` | React 18 SPA (93 pages, 37 services, 29 types) | +| **Backend v2** | `https://git.albousalh.com/devops/encoach_backend_new_v2.git` | Odoo 19 backend (27 custom + 14 OpenEduCat = 41 modules) | + +**Note:** The older repositories (`encoach_frontend_new_v1`, `encoach_be_odoo19`, `ielts-be-v0`) are superseded. All development should continue in the v2 repositories above. + +--- + +## 2. Staging Environment + +| Service | URL | +|---------|-----| +| **Frontend** | `http://5.189.151.117:3000` | +| **Backend (Odoo 19)** | `http://5.189.151.117:8069` | + +Deployment is automated via Git post-receive hooks. Push to `main` triggers rebuild. + +--- + +## 3. Documentation + +| Document | Status | Description | +|----------|--------|-------------| +| `ENCOACH_UNIFIED_SRS.md` (v2.0) | **Current** | Unified frontend + backend SRS with implementation traceability | +| `ENCOACH_ODOO19_BACKEND_SRS.md` (v3.0) | **Current** | Backend-specific SRS with all API contracts and data models | +| `ENCOACH_PRODUCT_DESCRIPTION.md` | **Current** | Non-technical product description | +| `ENCOACH_SYSTEM_FEATURES_GUIDE.md` | **Current** | System features guide by sidebar section | +| `ODOO_BACKEND_SRS_v3.md` | **Superseded** | Replaced by `ENCOACH_ODOO19_BACKEND_SRS.md` v3.0 | +| `ODOO_MIGRATION_SRS_v2.md` | **Superseded** | Replaced by `ENCOACH_ODOO19_BACKEND_SRS.md` v3.0 | +| `ODOO_MIGRATION_SRS.md` | **Superseded** | Replaced by `ENCOACH_ODOO19_BACKEND_SRS.md` v3.0 | +| `ODOO_MIGRATION_FRONTEND_SRS.md` | **Superseded** | Replaced by `ENCOACH_UNIFIED_SRS.md` v2.0 | + +--- + +## 4. What Was Implemented + +### Frontend (93 page components) + +- **28 root pages** -- login, register, FAQ, exam runner, etc. +- **33 admin pages** -- full LMS/platform administration +- **19 student pages** -- courses, adaptive learning, communication +- **14 teacher pages** -- course builder, AI workbench, grading +- **37 API service modules** calling ~280+ backend endpoints +- **14 AI components** wired to real backend AI services + +### Backend (41 Odoo modules, ~377 API routes) + +- **`encoach_api`** -- 16 controller files, ~120 routes (auth, users, entities, roles, exams, assignments, classrooms, stats, subscriptions, tickets, approvals, training, generation, AI analytics) +- **`encoach_lms_api`** -- 28 controller files, ~209 routes (courses, students, teachers, batches, timetable, attendance, grades, departments, academic, admissions, subject registration, institutional exams, course assignments, student leave, fees, lessons, gradebook, student progress, library, activities, facilities, notifications, FAQ, courseware, plagiarism, communication) +- **`encoach_adaptive_api`** -- 6 controller files, ~41 routes (taxonomy, diagnostic, proficiency, learning plans, content, coaching) +- **`encoach_resources`** -- 1 controller file, ~7 routes (resource CRUD) + +### Beyond Original SRS + +The developer also implemented: + +- Student Leave Management (types, requests, approve/reject) +- Fees Management (plans, student fees, terms) +- Lessons Management (timetable-linked) +- Gradebook and Grading Assignments +- Student Progress Tracking (aggregate) +- Library Management (media, movements, cards) +- Activity Management (configurable types) +- Facility and Asset Management +- Roles CRUD, User Role Assignment, Authority Matrix + +--- + +## 5. AI Service Credentials + +The developer needs API keys for: + +| Service | Purpose | +|---------|---------| +| **OpenAI** | GPT-4o and Whisper -- grading, coaching, content generation, speech-to-text | +| **AWS Polly** | Text-to-speech (neural voices) | +| **ELAI** | AI avatar video generation | +| **GPTZero** | AI writing detection | + +These are in `06-All-Credentials-Inventory.md` locally. Keys must be provided **separately** -- never committed to the git repo. On staging, they are in `/opt/encoach/backend-v2/.env`. + +--- + +## 6. Frontend Code Reference + +For any new backend development, the frontend contract is defined in: + +- **`src/services/*.ts`** (37 files) -- every URL path, request body shape, and response handling +- **`src/types/*.ts`** (29 files) -- all TypeScript interfaces the frontend expects from the API +- **`src/hooks/queries/*.ts`** (21 files) -- TanStack Query cache keys and query configurations