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
parent b02ee8b6b7
commit 571a08d0f7
1 changed files with 957 additions and 0 deletions
--- a/docs/EnCoach-Platform-User-Guide.md
+++ b/docs/EnCoach-Platform-User-Guide.md
@@ -0,0 +1,957 @@
+# 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*