devops/encoach_backend_new_v3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add project documentation and update README

Browse Source 
- README.md: replaced generic Odoo setup guide with project overview,
  module architecture diagram, staging info, and development instructions
- docs/ENCOACH_ODOO19_BACKEND_SRS.md v3.0: complete backend SRS with
  all 41 modules and ~377 API routes marked as implemented
- docs/ENCOACH_UNIFIED_SRS.md v2.0: unified platform SRS covering
  frontend, backend, and AI stack
- docs/ODOO_DEVELOPER_HANDOFF.md: implementation-complete handoff guide
- docs/ENCOACH_PRODUCT_DESCRIPTION.md: non-technical product description
- docs/ENCOACH_SYSTEM_FEATURES_GUIDE.md: system features reference guide

Made-with: Cursor
This commit is contained in:
devops
2026-04-06 12:58:26 +04:00
parent d9f8a62886
commit bdc6598734
6 changed files with 5866 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
README.md
View File

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

1959
docs/ENCOACH_ODOO19_BACKEND_SRS.md Normal file
View File

File diff suppressed because it is too large Load Diff

186
docs/ENCOACH_PRODUCT_DESCRIPTION.md Normal file
View File

@@ -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.*

308
docs/ENCOACH_SYSTEM_FEATURES_GUIDE.md Normal file
View File

@@ -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*

3223
docs/ENCOACH_UNIFIED_SRS.md Normal file
View File

File diff suppressed because it is too large Load Diff

100
docs/ODOO_DEVELOPER_HANDOFF.md Normal file
View File

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