encoach_backend_new_v3/docs/EnCoach-Platform-User-Guide.md

EnCoach Platform — Complete User Guide

Version: 4.0
Last Updated: April 11, 2026

---

Table of Contents

1. Getting Started
2. Student Guide
3. Teacher Guide
4. Admin Guide
5. Common Features
6. AI-Powered Features
7. Exam Workflow (End-to-End)
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