# EnCoach Platform — Complete User Guide

**Version:** 4.0  
**Last Updated:** April 11, 2026

---

## Table of Contents

1. [Getting Started](#1-getting-started)
2. [Student Guide](#2-student-guide)
3. [Teacher Guide](#3-teacher-guide)
4. [Admin Guide](#4-admin-guide)
5. [Common Features](#5-common-features)
6. [AI-Powered Features](#6-ai-powered-features)
7. [Exam Workflow (End-to-End)](#7-exam-workflow-end-to-end)
8. [Troubleshooting & FAQ](#8-troubleshooting--faq)

---

## 1. Getting Started

### 1.1 Accessing the Platform

| Environment | Frontend URL | Backend API |
|-------------|-------------|-------------|
| Local Dev | `http://localhost:8080` | `http://localhost:8069` |
| Production | `http://5.189.151.117:3000` | `http://5.189.151.117:8069` |

### 1.2 Logging In

1. Navigate to the platform URL
2. Enter your **Email** and **Password**
3. Click **Login**
4. You will be redirected to your role-specific dashboard:
   - **Students** → `/student/dashboard`
   - **Teachers** → `/teacher/dashboard`
   - **Admins** → `/admin/dashboard`
   - **Corporate/Agent** → `/admin/platform`

### 1.3 First-Time Users

- After registration and email verification, new users go through the **Onboarding Wizard** which collects learning goals and determines if a placement test is needed
- Students may be prompted to take a **Placement Test** to determine their CEFR level (A1–C2)

### 1.4 User Roles

| Role | Description | Access Level |
|------|-------------|--------------|
| **Student** | Learner enrolled in courses/exams | Own courses, exams, grades, progress |
| **Teacher** | Instructor managing courses | Own courses, student management, grading |
| **Admin** | Platform administrator | Full platform control, all modules |
| **Corporate** | Organization manager | Entity management, corporate stats |
| **Master Corporate** | Multi-org manager | Cross-entity management |

---

## 2. Student Guide

### 2.1 Dashboard
**Path:** `/student/dashboard`

Your home screen showing:
- Enrolled courses overview
- Upcoming exams and deadlines
- Recent grades
- Learning progress summary
- Quick links to active assignments

### 2.2 Courses

#### Browsing Courses
**Path:** `/student/courses`

- View all courses you are enrolled in
- See course progress percentage, teacher name, and schedule
- Click any course to view details

#### Course Detail
**Path:** `/student/courses/:id`

- View course description, syllabus, and materials
- Access course chapters and content
- Track your completion progress

#### Reading Chapter Content
**Path:** `/student/courses/:id/chapters/:chapterId`

- Read chapter materials (text, images, embedded media)
- Navigate between chapters using previous/next buttons
- Completion is tracked automatically

### 2.3 Adaptive Learning

#### Subject Selection
**Path:** `/student/subjects`

- Browse available subjects
- Select subjects you want to study
- Each subject has an adaptive learning path

#### Diagnostic Test
**Path:** `/student/diagnostic/:subjectId`

- Take a diagnostic test to assess your current level in a subject
- Results determine your personalized learning path
- Tests adapt to your responses in real time

#### Proficiency Profile
**Path:** `/student/proficiency/:subjectId`

- View your current proficiency level per subject
- See strengths and weaknesses across sub-skills
- Track how your proficiency changes over time

#### Learning Plan
**Path:** `/student/plan/:subjectId`

- View your personalized AI-generated learning plan
- See recommended topics in order of priority
- Track completion of each topic

#### Topic Learning
**Path:** `/student/topic/:topicId`

- Study a specific topic with curated materials
- Interactive exercises and practice questions
- AI-powered explanations and hints

### 2.4 Exams

#### Taking an Exam
**Path:** `/student/exam/:examId/session`

This is the full-screen exam delivery interface:

1. **Start** — Click "Begin Exam" to start the timer
2. **Navigate** — Use section tabs to switch between sections (Reading, Listening, Writing, Speaking)
3. **Answer** — Select answers for MCQ, type for fill-in-blank, write essays for writing tasks
4. **Auto-save** — Your answers are automatically saved every 30 seconds
5. **Review** — Click "Review" to see which questions are answered/unanswered
6. **Submit** — Click "Submit Exam" when done (or when time expires)

> **Important:** Once submitted, you cannot change your answers.

#### Exam Results
**Path:** `/student/exam/:examId/results`

- View your overall score and per-section breakdown
- See AI-generated feedback on each answer
- View correct answers for objective questions
- Check your IELTS band score (for IELTS exams)

#### Exam Status
**Path:** `/student/exam/:examId/status`

- Check if your exam is being graded
- See status: Submitted → Scoring → Released
- Some exams require manual approval before scores are visible

### 2.5 AI-Powered Courses

#### AI English Course
**Path:** `/student/course/ai-english/:courseId`

- AI-generated English course personalized to your level
- Interactive lessons covering grammar, vocabulary, reading, and writing
- Progress tracked automatically

#### AI IELTS Course
**Path:** `/student/course/ai-ielts/:courseId`

- IELTS-specific preparation course
- Covers all 4 IELTS skills: Reading, Listening, Writing, Speaking
- Practice with AI-generated IELTS-style questions
- Band score predictions

### 2.6 Placement Test

#### Briefing
**Path:** `/student/placement`

- Read instructions before starting the placement test
- Understand the test format and duration

#### Taking the Test
**Path:** `/student/placement/test`

- Adaptive test that determines your CEFR level
- Questions get harder or easier based on your answers
- Results determine which courses and content are recommended

#### Results
**Path:** `/student/placement/results`

- View your placement level (A1–C2)
- See skill-by-skill breakdown
- Recommended courses based on your level

### 2.7 Communication

#### Messages
**Path:** `/student/messages`

- Send and receive messages with teachers
- View conversation history

#### Discussions
**Path:** `/student/discussions`

- Participate in course discussion boards
- Ask questions and help classmates
- Teachers can respond to discussions

#### Announcements
**Path:** `/student/announcements`

- View announcements from teachers and administrators
- Important updates about courses, exams, and schedule changes

### 2.8 Progress & Grades

#### Grades
**Path:** `/student/grades`

- View all your grades across courses and exams
- Filter by course, date, or status
- Download grade reports

#### Learning Journey
**Path:** `/student/journey`

- Visual timeline of your learning progress
- Milestones achieved
- Skills gained over time

### 2.9 Account

#### Profile
**Path:** `/student/profile`

- Update personal information
- Change password
- Set notification preferences

---

## 3. Teacher Guide

### 3.1 Dashboard
**Path:** `/teacher/dashboard`

Your home screen showing:
- Active courses and student count
- Pending assignments to grade
- Upcoming schedule
- Quick stats on student performance

### 3.2 Course Management

#### My Courses
**Path:** `/teacher/courses`

- View all courses you teach
- See enrollment counts and completion rates
- Access course editing tools

#### Create a Course
**Path:** `/teacher/courses/new`

1. Fill in course title, description, and subject
2. Set enrollment limits and schedule
3. Add sections/chapters
4. Publish when ready

#### Edit a Course
**Path:** `/teacher/courses/:id/edit`

- Modify course settings, description, and materials
- Add/remove chapters and content
- Update enrollment settings

#### Course Chapters
**Path:** `/teacher/courses/:id/chapters`

- View and reorder chapters
- Add new chapters with content
- Set chapter visibility and prerequisites

#### Chapter Detail
**Path:** `/teacher/courses/:id/chapters/:chapterId`

- Edit chapter content (rich text editor)
- Add attachments, images, and videos
- Set chapter quizzes and exercises

#### AI Workbench
**Path:** `/teacher/courses/:id/workbench`

- Use AI to generate course content
- AI suggests materials, exercises, and assessments
- Edit and refine AI-generated content before publishing
- Batch optimize existing content

#### Course Progress
**Path:** `/teacher/course/:courseId/progress`

- View student progress across the course
- See per-chapter completion rates
- Identify students who are falling behind

### 3.3 Assignments

#### Assignment List
**Path:** `/teacher/assignments`

- View all assignments you've created
- Filter by course, status, or date
- See submission counts

#### Assignment Detail
**Path:** `/teacher/assignments/:id`

- View student submissions
- Grade assignments manually or with AI assistance
- Leave feedback on each submission
- Bulk grading tools

### 3.4 Student Management

#### My Students
**Path:** `/teacher/students`

- View all students across your courses
- See individual performance summaries
- Contact students directly

#### Attendance
**Path:** `/teacher/attendance`

- Record daily attendance
- View attendance history
- Generate attendance reports

### 3.5 Schedule

#### Timetable
**Path:** `/teacher/timetable`

- View your weekly teaching schedule
- See room assignments and time slots
- Sync with calendar

### 3.6 Communication

#### Discussions
**Path:** `/teacher/discussions`

- Manage course discussion boards
- Respond to student questions
- Pin important announcements

#### Announcements
**Path:** `/teacher/announcements`

- Create and publish announcements
- Target specific courses or all students
- Set announcement priority

### 3.7 Adaptive Learning Settings

**Path:** `/teacher/adaptive/settings`

- Configure adaptive learning parameters for your courses
- Set difficulty progression rules
- Customize AI behavior for student recommendations

### 3.8 Account

#### Profile
**Path:** `/teacher/profile`

- Update professional information
- Set office hours
- Manage notification settings

---

## 4. Admin Guide

### 4.1 Dashboards

#### LMS Dashboard
**Path:** `/admin/dashboard`

- Overview of all courses, students, teachers, and batches
- Charts: enrollment trends, completion rates, active users
- Quick actions to manage platform

#### Platform Dashboard
**Path:** `/admin/platform`

- Entity-level overview (for multi-organization setups)
- Revenue stats, ticket counts
- Cross-entity comparisons

### 4.2 Exam Management

#### Generation Page (AI-Powered)
**Path:** `/admin/generation`

The main exam creation tool. Create complete exams with AI:

1. **Fill Header** — Enter exam title, label, and select a structure
2. **Select Modules** — Choose from Reading, Listening, Writing, Speaking, Level, Industry
3. **Configure Per Module:**
   - Timer (minutes)
   - Difficulty level (A1–C2 CEFR tags)
   - Access type (Private/Public)
   - Approval workflow
   - Grading system
   - Shuffling toggle

4. **Reading Module:**
   - Add passages (1–3+)
   - AI generates passage text from a topic
   - Select exercise types: Multiple Choice, Fill Blanks, Write Blanks, True/False, Paragraph Match
   - Generate exercises from the passage

5. **Listening Module:**
   - Add sections: Social Conversation, Social Monologue, Academic Discussion, Academic Monologue
   - AI generates conversation/monologue context
   - Generate audio (Text-to-Speech via ElevenLabs)
   - Select exercise types

6. **Writing Module:**
   - Add Task 1 (letter) and Task 2 (essay)
   - AI generates task instructions
   - Set word limits and marks

7. **Speaking Module:**
   - Add Speaking 1, Speaking 2, Interactive Speaking
   - AI generates examiner scripts
   - Select avatar for video generation (Gia, Vadim, Orhan, Flora, Scarlett, Parker, Ethan)
   - Generate video with AI avatar

8. **Submit:**
   - "Submit for approval" — creates exam in draft status
   - "Skip approval" — publishes immediately

#### Exam Structures
**Path:** `/admin/exam-structures`

- Create reusable exam structure templates
- Define which modules are included
- Set per-structure industry and entity
- Delete outdated structures

#### IELTS Exam Creation
**Path:** `/admin/exam/ielts/create` → `/admin/exam/ielts/:examId/skills` → `/admin/exam/ielts/:examId/content` → `/admin/exam/ielts/:examId/validate`

Step-by-step IELTS exam creation:
1. **Create** — Set title, template, entity
2. **Skills** — Configure skills (reading, listening, writing, speaking)
3. **Content Pool** — Auto-assemble questions from the content pool
4. **Validate** — Check all sections have enough questions before publishing

#### Custom Exam Creation
**Path:** `/admin/exam/custom/create`

- Create non-IELTS exams with flexible section structure
- Add sections with any skill type
- Assign questions manually or auto-assemble

#### Exams List
**Path:** `/admin/examsList`

- View all exams across the platform
- Filter by status, module, entity
- Quick actions: edit, delete, assign

#### Grading Queue
**Path:** `/admin/exam/:examId/grading`

- View submissions waiting for grading
- AI suggests grades for written/spoken answers
- Accept, modify, or override AI grades
- Submit final grades

#### Score Approval
**Path:** `/admin/scores/pending`

- Review scores pending approval
- Approve or reject score releases
- Bulk approval actions

#### Exam Sessions
**Path:** `/admin/exam-sessions`

- Manage institutional exam sessions
- Schedule exam dates and rooms
- Monitor active sessions

### 4.3 User Management

#### Users
**Path:** `/admin/users`

- List all platform users
- Filter by role (student, teacher, admin, corporate)
- Create, edit, or deactivate users

#### Roles & Permissions
**Path:** `/admin/roles-permissions`

- Define custom roles
- Assign permissions per role
- View permission matrix

#### User Roles
**Path:** `/admin/user-roles`

- Assign roles to specific users
- Bulk role assignment

#### Authority Matrix
**Path:** `/admin/authority-matrix`

- Define who can approve what
- Set multi-level approval chains

### 4.4 Academic Management

#### Students
**Path:** `/admin/students`

- Full student management
- View enrollments, grades, attendance
- Bulk student operations

#### Teachers
**Path:** `/admin/teachers`

- Manage teacher profiles
- Assign courses and batches

#### Courses
**Path:** `/admin/courses`

- All courses across the institution
- Create, edit, archive courses

#### Batches
**Path:** `/admin/batches`

- Group students into batches
- Assign batches to courses/exams

#### Timetable
**Path:** `/admin/timetable`

- Institution-wide schedule management
- Room and time slot allocation

#### Attendance
Managed through teacher interface; admin can view reports.

#### Gradebook
**Path:** `/admin/gradebook`

- Institution-wide grade overview
- Export grade reports

#### Marksheets
**Path:** `/admin/marksheets`

- Generate and print official marksheets
- Per-student or per-batch

### 4.5 LMS Content

#### Course Configuration
**Path:** `/admin/course/configure/:courseId`

- Advanced course settings
- Set prerequisites, completion rules
- Configure grading scheme

#### Module Builder
**Path:** `/admin/course/:courseId/modules`

- Build course modules and content
- Drag-and-drop module ordering
- AI-assisted content generation

#### Lessons
**Path:** `/admin/lessons`

- Manage individual lessons
- Schedule lessons across batches

### 4.6 Adaptive Learning

#### Taxonomy Manager
**Path:** `/admin/taxonomy`

- Manage subject taxonomies (subjects → topics → sub-topics)
- Set difficulty levels and prerequisites
- Configure adaptive progression rules

#### Resource Manager
**Path:** `/admin/resources`

- Upload and manage learning resources
- Link resources to topics
- Categorize by type (video, article, exercise, etc.)

#### Adaptive Dashboard
**Path:** `/admin/adaptive/dashboard`

- Overview of adaptive learning across the platform
- See which students are on track vs struggling
- System-wide learning analytics

#### Student Adaptive Detail
**Path:** `/admin/adaptive/student/:studentId`

- Deep dive into a specific student's adaptive path
- View learning events and signals
- Override AI recommendations if needed

### 4.7 AI Management

#### AI English Quality
**Path:** `/admin/ai-course/english/:courseId/quality`

- Review AI-generated English course content quality
- Approve or reject generated materials
- Edit content before publishing

#### AI English Taxonomy
**Path:** `/admin/ai-course/english/taxonomy`

- Manage the taxonomy that drives AI English course generation
- Add/edit topics and difficulty mappings

#### AI IELTS Validation
**Path:** `/admin/ai-course/ielts/:courseId/validation`

- Validate AI-generated IELTS content
- Ensure question quality and accuracy
- Approve for student access

### 4.8 Entity & Organization

#### Entities
**Path:** `/admin/entities`

- Manage organizations (schools, companies, etc.)
- Set entity-level settings
- View entity statistics

#### Level Mapping
**Path:** `/admin/entity/:entityId/level-mapping`

- Map CEFR levels to entity-specific levels
- Configure level thresholds

#### White-Label Branding
**Path:** `/admin/entity/:entityId/branding`

- Customize platform appearance per entity
- Upload logos, set colors
- Custom domain settings

#### Bulk Student Upload
**Path:** `/admin/entity/students/upload`

- Upload students via CSV/Excel
- Map columns to student fields
- Preview and confirm before import

#### Credential Dashboard
**Path:** `/admin/entity/students/credentials`

- Manage student login credentials
- Bulk password reset
- View credential status

### 4.9 Admissions

#### Admission List
**Path:** `/admin/admissions`

- View all admission applications
- Filter by status (pending, approved, rejected)

#### Admission Detail
**Path:** `/admin/admissions/:id`

- Review application details
- Approve or reject with comments

#### Admission Register
**Path:** `/admin/admission-register`

- Configure admission periods and requirements
- Set document requirements
- Manage admission quotas

### 4.10 Financial

#### Fees
**Path:** `/admin/fees`

- Manage fee structures
- View payment status per student
- Generate invoices

#### Payment Records
**Path:** `/admin/payment-record`

- View all payment transactions
- Filter by date, student, status
- Export payment reports

### 4.11 Training Modules

#### Vocabulary
**Path:** `/admin/training/vocabulary`

- Manage vocabulary content and exercises
- Create word lists by topic and level

#### Grammar
**Path:** `/admin/training/grammar`

- Manage grammar lessons and exercises
- Create grammar rules and practice sets

### 4.12 Configuration

#### Platform Settings
**Path:** `/admin/settings-platform`

- Global platform configuration
- API key management (OpenAI, ElevenLabs, AWS, etc.)
- System defaults

#### LMS Settings
**Path:** `/admin/settings`

- LMS-specific settings
- Grading policies
- Enrollment rules

#### Approval Workflows
**Path:** `/admin/approval-workflows` and `/admin/approval-config`

- Define approval steps for content, exams, scores
- Set required approvers per workflow

#### Notification Rules
**Path:** `/admin/notification-rules`

- Configure when and how notifications are sent
- Set triggers (new assignment, grade release, etc.)
- Choose channels (email, in-app, SMS)

#### FAQ Manager
**Path:** `/admin/faq`

- Create and manage FAQ entries
- Categorize by topic
- Publish to the public FAQ page

### 4.13 Support

#### Tickets
**Path:** `/admin/tickets`

- View support tickets from users
- Assign to team members
- Track resolution status

### 4.14 Reports & Analytics

#### Reports
**Path:** `/admin/reports`

- Generate institutional reports
- Student performance analytics
- Course effectiveness metrics

#### Student Performance
**Path:** `/admin/student-performance`

- Detailed student performance analysis
- Compare across batches and courses
- Export data

#### Corporate Stats
**Path:** `/admin/stats-corporate`

- Corporate-level analytics
- Multi-entity comparisons
- ROI metrics

---

## 5. Common Features

### 5.1 Public Pages

| Feature | URL | Description |
|---------|-----|-------------|
| FAQ | `/faq` | Browse frequently asked questions |
| Score Verification | `/verify/:hash` | Verify a certificate or score by unique hash |
| Admission Application | `/apply` | Public multi-step admission form |
| Password Reset | `/forgot-password` | Request a password reset email |

### 5.2 AI Features Available to All

- **AI Tip Banner** — contextual AI tips displayed on relevant pages
- **AI Search** — intelligent search across platform content
- **AI Study Coach** — personalized study recommendations (students)
- **AI Writing Helper** — real-time writing assistance (during exams/assignments)
- **AI Grade Explainer** — explains why you received a specific grade

---

## 6. AI-Powered Features

### 6.1 Content Generation (Admin)

| Feature | Module | What It Does |
|---------|--------|--------------|
| Passage Generation | Reading | AI creates reading passages at specified CEFR level and topic |
| Exercise Generation | Reading | AI creates MCQ, Fill Blanks, True/False, etc. from a passage |
| Context Generation | Listening | AI creates conversation/monologue transcripts |
| Audio Generation | Listening | Text-to-Speech converts transcripts to audio (ElevenLabs) |
| Instruction Generation | Writing | AI creates writing task instructions |
| Script Generation | Speaking | AI creates speaking exam scripts with examiner questions |
| Avatar Video | Speaking | AI generates video of an avatar delivering the speaking script |
| Course Content | Courses | AI generates lesson content, materials, and exercises |
| Material Suggestions | Workbench | AI suggests relevant learning materials for a topic |

### 6.2 Assessment (Teacher/Admin)

| Feature | What It Does |
|---------|--------------|
| AI Grading Suggestions | AI scores written and spoken answers with explanations |
| AI Batch Optimizer | Optimize multiple content items at once |
| AI Insights | Analytics and patterns in student performance |

### 6.3 Learning (Student)

| Feature | What It Does |
|---------|--------------|
| Adaptive Learning Path | AI adjusts content difficulty based on performance |
| AI Study Coach | Personalized study tips and recommendations |
| AI Writing Helper | Real-time writing feedback and suggestions |
| Gap Analysis | AI identifies knowledge gaps and generates targeted courses |

### 6.4 Supported AI Services

| Service | Provider | Used For |
|---------|----------|----------|
| GPT-4o | OpenAI | Content generation, grading, feedback |
| GPT-3.5 Turbo | OpenAI | Fast/lightweight generation tasks |
| ElevenLabs | ElevenLabs | Text-to-Speech (listening audio) |
| AWS Polly | Amazon | Alternative TTS provider |
| ELAI | ELAI.io | Avatar video generation (speaking) |
| GPTZero | GPTZero | AI content detection |
| Sentence Transformers | HuggingFace | Vector embeddings for RAG search |

---

## 7. Exam Workflow (End-to-End)

### Step 1: Admin Creates Exam

1. Go to `/admin/generation`
2. Enter exam title and select modules
3. Generate content with AI for each module
4. Submit for approval or publish directly

### Step 2: Admin Assigns Exam

1. Go to `/admin/examsList`
2. Select the exam
3. Assign to students or batches
4. Set access window (start/end dates)

### Step 3: Student Takes Exam

1. Student sees exam on `/student/dashboard`
2. Clicks to start → `/student/exam/:examId/session`
3. Answers questions within time limit
4. Submits exam

### Step 4: AI + Teacher Grading

1. Objective questions (MCQ, T/F) are auto-graded instantly
2. Subjective questions (writing, speaking) go to grading queue
3. Teacher views at `/admin/exam/:examId/grading`
4. AI suggests grades → teacher approves/modifies
5. Final grades are submitted

### Step 5: Score Approval (if configured)

1. Admin reviews scores at `/admin/scores/pending`
2. Approves or requests re-grading
3. Scores are released to students

### Step 6: Student Views Results

1. Student sees notification
2. Views results at `/student/exam/:examId/results`
3. Sees score breakdown, AI feedback, and correct answers

---

## 8. Troubleshooting & FAQ

### Q: I can't log in
- Check that your email and password are correct
- If you forgot your password, use `/forgot-password`
- Contact your admin if your account is deactivated

### Q: My exam score is not showing
- Scores may be pending teacher grading (check exam status)
- Scores may require admin approval before release
- Contact your teacher if it's been more than 48 hours

### Q: AI generation is not working
- Check that AI keys are configured in `/admin/settings-platform` (admin)
- Check the OpenAI API key is valid and has credits
- Check Odoo settings at `http://localhost:8069/odoo/settings` for EnCoach AI Services

### Q: I see "Access Denied" errors
- Your role may not have permission for that page
- Contact your admin to verify your role and permissions
- Log out and log back in to refresh your session

### Q: Audio/Video is not generating
- ElevenLabs API key is required for audio generation
- ELAI API key is required for avatar video generation
- Check these in the AI Settings page (admin)

### Q: How do I change my CEFR level?
- Take a diagnostic test at `/student/diagnostic/:subjectId`
- Or ask your teacher to manually adjust your level

---

*EnCoach Platform v4.0 — Built with Odoo 19, React 18, TypeScript, and AI*