Files
encoach_backend_new_v3/docs/EnCoach-Platform-User-Guide.md
Yamen Ahmad 571a08d0f7 docs: add comprehensive platform user guide for all user types
Covers Student, Teacher, Admin roles with every page/feature documented:
- 30+ student features (courses, exams, adaptive learning, AI courses)
- 17+ teacher features (course management, grading, workbench)
- 60+ admin features (generation, exam management, LMS, analytics)
- AI features guide (7 generation types, grading, coaching)
- End-to-end exam workflow (create → assign → take → grade → release)
- Troubleshooting & FAQ section

Made-with: Cursor
2026-04-11 14:40:20 +04:00

958 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 (A1C2)
### 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 (A1C2)
- 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 (A1C2 CEFR tags)
- Access type (Private/Public)
- Approval workflow
- Grading system
- Shuffling toggle
4. **Reading Module:**
- Add passages (13+)
- 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*