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

docs: add comprehensive platform user guide for all user types

Browse Source 
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
This commit is contained in:
Yamen Ahmad
2026-04-11 14:40:20 +04:00
parent b02ee8b6b7
commit 571a08d0f7
1 changed files with 957 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

957
docs/EnCoach-Platform-User-Guide.md Normal file
View File

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