# EnCoach — User Manual > *Unlock your potential with AI-powered learning.* This manual walks every user type through the EnCoach platform: what each portal looks like, which features are available, and how to accomplish the most common tasks. It's written to be opened by a first-time user and followed step-by-step. The platform has **four main user types**, each with its own portal: | Role | Portal URL prefix | Purpose | | ------------------- | ----------------- | ----------------------------------------------------------------- | | **Student** | `/student/*` | Learn, practice, take exams, track progress. | | **Teacher** | `/teacher/*` | Run courses, grade assignments, manage classrooms. | | **Admin** | `/admin/*` | Operate the institution: users, courses, exams, reports, payments.| | **Corporate / Agent / Developer** | `/admin/*` | Admin portal with scoped permissions (see §Admin — Access matrix).| --- ## Table of contents 1. [Getting started — common to all users](#1-getting-started--common-to-all-users) 2. [Student guide](#2-student-guide) 3. [Teacher guide](#3-teacher-guide) 4. [Admin guide](#4-admin-guide) 5. [Privacy & language controls (all roles)](#5-privacy--language-controls-all-roles) 6. [Troubleshooting & support](#6-troubleshooting--support) --- ## 1. Getting started — common to all users ### 1.1 Signing in 1. Open the platform URL in your browser. You'll land on `/login`. 2. Enter your **email** and **password**. 3. Click **Sign in**. If you've been invited via email, you may need to verify your address first. Open the link in the invitation email and follow the prompts. ### 1.2 Registering a new account 1. From the login page, click **Register**. 2. Fill in your name, email, and chosen password. 3. Check your inbox for the verification email and click the link to confirm. 4. First-time users are automatically routed through an **onboarding wizard** that collects your goals, proficiency hints, and preferred subjects. ### 1.3 Forgot / reset password - Click **Forgot password** on `/login`. - Enter your email. You'll get a reset link valid for a short time. - Follow the link, set a new password, then sign in. ### 1.4 Switching theme (dark / light) Every portal has a **sun / moon toggle** in the header. Click it to cycle **Light → Dark → System**. Your choice is remembered per browser. ### 1.5 Switching language Every portal also has a **globe icon** next to the theme toggle. Pick **English** or **العربية**. If you choose Arabic, the interface switches to right-to-left automatically. ### 1.6 Sign out Click your avatar in the top-right of any portal and pick **Sign out**. Your session is revoked server-side (not just cleared locally). --- ## 2. Student guide The student portal is your personal learning environment: courses, assignments, exams, attendance, and AI-powered practice. ### 2.1 Dashboard — `/student/dashboard` This is your home screen. It shows: - **Next up** — the next class, assignment, or exam on your timetable. - **Progress widgets** — overall mastery, adaptive subjects in progress, recent exam scores. - **Announcements** — school-wide and course-specific notices from teachers and admins. ### 2.2 My courses — `/student/courses` - Lists every course you're enrolled in. - Click a course card to open **`/student/courses/:id`** — the course detail page with: - Syllabus - Chapter list (click any chapter to read content, watch videos, and take embedded exercises). - Assignments tied to the course. - Teacher and classmates. ### 2.3 AI-driven courses (the core of the platform) EnCoach's flagship is the adaptive AI coach. There are two flows: #### 2.3.1 General English — `/student/course/ai-english/:courseId` - Auto-generated lessons scoped to your current CEFR level. - Each lesson includes: reading, vocabulary, grammar drill, listening, speaking prompt, and a short review quiz. - **Thumbs up / down** under every AI-generated item — your feedback feeds the admin triage queue and improves future prompts. #### 2.3.2 IELTS — `/student/course/ai-ielts/:courseId` - Full IELTS prep: Reading, Listening, Writing Task 1 & 2, Speaking. - Every generated item is validated against the IELTS rubric before you see it. Items that fail validation never reach you. ### 2.4 Adaptive learning — personalized practice If you choose to pursue an adaptive track: 1. Go to **`/student/subjects`** and pick a subject (e.g. Vocabulary, Grammar, Reading). 2. Take the **diagnostic test** at **`/student/diagnostic/:subjectId`**. Results map your ability onto a skill tree. 3. Review your **proficiency profile** at **`/student/proficiency/:subjectId`** — heatmap of strong / weak areas. 4. Follow the generated **learning plan** at **`/student/plan/:subjectId`**. 5. Drill individual topics via **`/student/topic/:topicId`**. ### 2.5 Placement tests — `/student/placement` For corporate / institutional students who need a CEFR placement: 1. **`/student/placement`** — briefing page: rules, duration, tech check. 2. **`/student/placement/test`** — full-screen exam session (no layout chrome). 3. **`/student/placement/results`** — your band score + per-skill breakdown + recommended starting level. 4. **`/student/placement/access`** — access code entry for managed institutional tests. ### 2.6 Assignments — `/student/assignments` - Table of all current and past assignments. - Click an assignment to upload your submission, view rubric, and track grading status. ### 2.7 Grades — `/student/grades` - Per-course gradebook view. - Drill into each exam / assignment to see rubric-level feedback. ### 2.8 Exams - **Take an exam:** `/student/exam/:examId/session` — full-screen, distraction-free session. Answers auto-save. - **Check status:** `/student/exam/:examId/status` — submission state (grading, pending review, scored). - **See results:** `/student/exam/:examId/results` — band score, per-section breakdown, teacher / AI feedback. ### 2.9 Attendance — `/student/attendance` - Calendar + list view of your attendance history. - Export as CSV for personal records. ### 2.10 Timetable — `/student/timetable` - Week view of your classes, exams, and assignment deadlines. ### 2.11 Discussion boards — `/student/discussions` - Per-course forum threads. Ask questions, reply to classmates. ### 2.12 Announcements — `/student/announcements` - Institution-wide and course-specific announcements from teachers and admins. ### 2.13 Messages — `/student/messages` - Direct chat with your teachers and classmates. ### 2.14 Journey — `/student/journey` - A visual timeline of your progress: milestones hit, badges earned, exams passed, current level, next goals. ### 2.15 Profile — `/student/profile` - Name, email, phone, bio, avatar. - Change password. - Preferred language + theme. ### 2.16 Subject registration — `/student/subject-registration` - For institutions that require formal subject enrollment per term. --- ## 3. Teacher guide The teacher portal is your classroom command center. ### 3.1 Dashboard — `/teacher/dashboard` - **My classes today**, pending gradings, upcoming exams. - **Recent student activity** — who submitted, who's late, who's struggling (from adaptive signals). - Quick links to create an assignment or open your course builder. ### 3.2 My courses — `/teacher/courses` - All courses you teach. - Click **+ New course** to open the **course builder** (`/teacher/courses/new`): - Course metadata (title, description, cover, CEFR level). - Syllabus blocks. - Chapter list (each chapter has its own content editor + AI workbench). - Edit an existing course via **`/teacher/courses/:id/edit`**. ### 3.3 Chapters — `/teacher/courses/:courseId/chapters` - Ordered list of chapters for a course. - Click a chapter → **`/teacher/courses/:courseId/chapters/:chapterId`** to edit content, attach resources, add exercises, and configure the pass criteria. ### 3.4 AI workbench — `/teacher/courses/:courseId/workbench` The magic. From one panel you can: - Generate a new set of exercises (multiple choice, cloze, reading comprehension, short-answer) from a topic prompt. - Regenerate individual items with a different difficulty / style. - Preview exactly what students will see. - Submit generated items to the **exam review queue** if they're destined for a graded exam (items enter `pending_review` until an admin approves them). Every generation call is logged with the prompt hash and model so you can later ask **"why was this question generated this way?"** and get a traceable answer. ### 3.5 Assignments — `/teacher/assignments` - List of assignments you've issued. - Click one → **`/teacher/assignments/:id`** to: - See every student's submission. - Grade with the rubric. - Leave written / voice feedback. - Publish the grade (feeds the student gradebook in real time). ### 3.6 Students — `/teacher/students` - Roster of every student enrolled in a course you teach. - Click a student to open their profile, see per-topic mastery, and drill into individual attempts. ### 3.7 Attendance — `/teacher/attendance` - Per-class attendance register. - Mark present / absent / late in bulk. - Attendance automatically rolls up to the student dashboard and to admin reports. ### 3.8 Timetable — `/teacher/timetable` - Your weekly teaching schedule. ### 3.9 Library — `/teacher/library` - Reusable resource pool: PDFs, videos, slide decks, audio prompts. - Tag resources by topic / skill / CEFR level. - Attach them into chapters or assignments with one click. ### 3.10 Course progress — `/teacher/course/:courseId/progress` - Class heatmap: which chapters / topics are lagging, which students need attention, completion % per module. ### 3.11 Discussions & announcements - **`/teacher/discussions`** — moderate course forums, pin useful threads. - **`/teacher/announcements`** — post a notice to a course, a class, or the whole institution (if your role allows). ### 3.12 Adaptive settings — `/teacher/adaptive/settings` Configure how the adaptive engine behaves for your students: - Difficulty ramp steepness. - Mastery threshold to move on. - How many wrong answers before a remediation branch triggers. ### 3.13 Profile & privacy - **`/teacher/profile`** — personal details, signature, teaching bio. - **`/teacher/privacy`** — export your data / delete account (see §5). --- ## 4. Admin guide The admin portal is the operational hub of the institution. Under the hood it's a unified layout covering the original platform pages *plus* the full LMS *plus* the AI control plane. ### 4.1 Access matrix | Role | Sees | Typical use case | | ----------------- | ---------------------------------------------------------------- | ---------------------------------------- | | `admin` | Everything. | Institution owner / operations lead. | | `corporate` | Their corporate entity only (users, reports, exams). | Corporate HR manager. | | `mastercorporate` | Multiple corporate entities they own. | Corporate group head. | | `agent` | Assigned cohorts of students + scoring queue. | Scoring / review agent. | | `developer` | Full + dev-only tools (OpenAPI, feature flags). | Platform engineer. | All admin URLs start with `/admin/*`. ### 4.2 Dashboards - **`/admin/dashboard`** — LMS dashboard: enrolments, active courses, attendance trends, open tickets, revenue. - **`/admin/platform`** — legacy platform dashboard kept for multi-tenant statistics (per-entity breakdown). ### 4.3 Academic setup | Page | What you do there | | ---------------------------- | ---------------------------------------------------------- | | `/admin/academic-years` | Define terms / academic years. | | `/admin/departments` | Departments within the institution. | | `/admin/courses` | All courses, enabled / disabled, owners. | | `/admin/batches` | Student cohorts — `/admin/batches/:id` for roster + schedule. | | `/admin/timetable` | Institution-wide timetable editor. | | `/admin/lessons` | Centralized lesson plan bank. | | `/admin/library` | Institutional content library. | | `/admin/facilities` | Rooms, labs, equipment bookings. | | `/admin/activities` | Extra-curricular activities, clubs, events. | ### 4.4 People | Page | What you do there | | ----------------------------- | --------------------------------------------------------- | | `/admin/students` | Student roster — search, filter, open a profile. | | `/admin/teachers` | Teacher roster. | | `/admin/admissions` | Applications pipeline — `/admin/admissions/:id` per file. | | `/admin/admission-register` | Bulk register newly admitted students. | | `/admin/entity/students/upload`| CSV bulk upload with validation + preview. | | `/admin/entity/students/credentials` | Reset passwords / send invites in bulk. | | `/admin/student-leave` | Approve / reject leave requests. | ### 4.5 Exams & assessments This is where most of the recent work landed. Flow: 1. **Pick a template** — `/admin/exam/create` (template selection). 2. **IELTS path**: - Create: `/admin/exam/ielts/create` - Configure skills: `/admin/exam/ielts/:examId/skills` - Build content pool: `/admin/exam/ielts/:examId/content` - Validate against rubric: `/admin/exam/ielts/:examId/validate` 3. **Custom exam path**: `/admin/exam/custom/create` — free-form exam builder with section / weighting / time budget controls. 4. **Human-in-the-loop review** (NEW) - **`/admin/exam/review-queue`** — every exam whose items are in `pending_review`. Filter by course, subject, or date. - **`/admin/exam/review/:examId`** — side-by-side view: each item with its AI-generated content, source passage, and buttons to **Approve**, **Edit & approve**, or **Reject** (with required reason). Approved exams become publishable. 5. **Grading queue**: `/admin/exam/:examId/grading` — human grader pick-list for writing / speaking items. 6. **Score approval queue**: `/admin/scores/pending` — final sign-off before scores are released to students. 7. **Institutional exam sessions**: `/admin/exam-sessions` — scheduled sittings for on-site administered exams. 8. **Marksheets**: `/admin/marksheets` — bulk marksheet generation and export. 9. **Exams list**: `/admin/examsList` — master list, filter by state (draft / pending_review / published / archived). 10. **Exam structures**: `/admin/exam-structures` — reusable blueprints (section counts, weighting, time budgets). 11. **Rubrics**: `/admin/rubrics` — rubric library used by both graders and the AI validator. 12. **Assignments**: `/admin/assignments` — assignment oversight across all courses. 13. **AI English quality** (`/admin/ai-course/english/:courseId/quality`) and **IELTS validation** (`/admin/ai-course/ielts/:courseId/validation`) — deep dive into the quality signals on a single AI-generated course. ### 4.6 AI control plane (NEW) Three pages to operate the AI itself: - **`/admin/generation`** — legacy generation page (bulk item creation from a prompt). - **`/admin/ai/prompts`** — **AI Prompt Editor**. Every prompt template lives here with versions. Features: - List all prompt keys (latest version per key). - Click a key to see all historical versions. - **Activate** any version (only one active per key at a time). - **Create new version** — title, description, template body, optional "activate immediately" flag. - **Render preview** — plug in sample variables and dry-run the template to see the exact text the LLM will receive, without actually calling the LLM. - **`/admin/ai/feedback`** — **AI Feedback Triage**. Every thumbs up/down a student leaves on AI-generated content lands here. Features: - Filter by status (open / acknowledged / fixed / dismissed), rating, subject type. - Click a feedback row to see the full comment, the AI output the student rated, and the prompt + version that produced it. - Resolve with status + optional note. Resolution is audited. ### 4.7 Taxonomy & resources - **`/admin/taxonomy`** — hierarchical taxonomy editor (subject → topic → sub-topic → skill). Used for tagging questions, embeddings, and learning plans. - **`/admin/resources`** — content resource manager (files, videos, external links) with access control. ### 4.8 Reports - **`/admin/reports`** — LMS reports dashboard (enrolment, attendance, performance, revenue). - **`/admin/student-performance`** — institution-wide performance heatmap. - **`/admin/stats-corporate`** — corporate-scoped KPIs (for corporate / mastercorporate roles). - **`/admin/record`** — audit trail / activity log browser. - **`/admin/gradebook`** — master gradebook across all courses. - **`/admin/student-progress`** — progress tracker for adaptive students. All reports now use SQL aggregation under the hood, so pages load in ~hundreds of milliseconds even at institution scale. ### 4.9 Finance - **`/admin/fees`** — fee structure, invoicing, per-student balance. - **`/admin/payment-record`** — payment history (including Paymob transactions with webhook-verified status). - Paymob checkout is available to students via the subscription flow; webhook events update order status automatically. ### 4.10 Governance & access control - **`/admin/roles-permissions`** — role editor (what each role can do). - **`/admin/authority-matrix`** — visual matrix: role × resource → CRUD permissions. - **`/admin/user-roles`** — assign roles to users. - **`/admin/approval-workflows`** — define approval chains (e.g. exam publish needs 2 approvers). - **`/admin/approval-config`** — per-workflow configuration. - **`/admin/notification-rules`** — which events trigger emails / in-app notifications, to whom. ### 4.11 Content & UX management - **`/admin/faq`** — manage the public FAQ (served at `/faq`). - **`/admin/entity/:entityId/branding`** — white-label per corporate entity: logo, colors, email sender. - **`/admin/entity/:entityId/level-mapping`** — map your institution's internal levels to CEFR. ### 4.12 Adaptive operations - **`/admin/adaptive/dashboard`** — adaptive-engine health across all students (average mastery, struggling-student alerts, remediation success rate). - **`/admin/adaptive/student/:studentId`** — deep dive into one student's signals and auto-adjustments. ### 4.13 Classrooms, training modules, and legacy pages - **`/admin/classrooms`** — physical classroom setup (rooms, capacity). - **`/admin/training/vocabulary`** and **`/admin/training/grammar`** — legacy training module editors kept for continuity with earlier platform content. - **`/admin/users`** — low-level user CRUD (prefer `/admin/students` / `/admin/teachers` for day-to-day work). - **`/admin/entities`** — multi-tenant entity manager (institutions / corporates). ### 4.14 Tickets & support - **`/admin/tickets`** — helpdesk inbox. Tickets fire notifications on status and assignee change, so nobody is left hanging. ### 4.15 Settings - **`/admin/settings`** — LMS-wide settings (term dates, grading scale, email templates). - **`/admin/settings-platform`** — platform-level settings (rate limits, feature flags, integrations). --- ## 5. Privacy & language controls (all roles) ### 5.1 Privacy Center — `//privacy` Available to students, teachers, and admins. Two actions: 1. **Export my data** — downloads a JSON file containing everything the platform stores about you (profile, courses, attempts, messages, logs). GDPR Article 20 compliant. 2. **Delete my account** — type `DELETE` to confirm. Effect: - PII is anonymized. - Personal records are removed. - User ID is nulled on audit logs (logs themselves are kept for legal retention). - Account is deactivated and cannot sign in again. - A tombstone record (`encoach.gdpr.erasure.request`) is written so the institution has proof of compliance. - Admins **cannot** self-erase via this flow (so there's always at least one admin left). Admins must request erasure via another admin. ### 5.2 Language toggle Next to the theme toggle in every portal header. Choose **English** or **العربية**. Arabic flips the UI to RTL automatically and the choice is remembered across sessions. --- ## 6. Troubleshooting & support ### 6.1 "I can't sign in" - Double-check email (no leading / trailing space). - Try **Forgot password** → reset. - Check your email for a verification link if your account is brand new. - If still stuck, contact your admin (students / teachers) or open a support ticket via `/faq` (public) or `/admin/tickets` (admins). ### 6.2 "The AI coach feels stuck / slow" - OpenAI calls time out at 30 s; if the provider is having a bad minute, the page surfaces an error instead of hanging. Retry. - If it happens repeatedly, report it from the thumbs-down button on the coach — it lands in the admin AI Feedback Triage queue with full context (prompt + version + output). ### 6.3 "An exam question looks wrong / biased / broken" - Click **thumbs-down** under the item and leave a short comment. Admins see it in `/admin/ai/feedback` and can acknowledge / fix / dismiss. ### 6.4 "My score is wrong" - Open the exam results page (`/student/exam/:examId/results`) and use **Request review**. It opens a ticket visible to your teacher and to admin; they can override via `/admin/scores/pending`. ### 6.5 "Payment failed / hasn't reflected" - Paymob updates arrive via a signed webhook, usually within seconds. If your payment still shows as unpaid after 5 minutes: - Students: open a support ticket from your dashboard. - Admins: check `/admin/payment-record` and the `encoach.paymob.order` logs — the last event payload and HMAC are stored for investigation. ### 6.6 "The page is blank / shows a spinner forever" - The app uses lazy-loaded routes; if the network chunk fails to load, a refresh usually fixes it. - Clear site data for the domain if the auth token is stuck. - Open the browser console and share the error with your admin / support. ### 6.7 Reporting issues to the platform team - Admins: `/admin/tickets` → new ticket. - Students & teachers: ask your institution admin, or use `/faq` for self-service. - Engineering escalation: open an issue on `https://git.albousalh.com/yamen/full_encoach_platform` with: 1. What you were trying to do. 2. What happened (exact text of any error). 3. Your role (student / teacher / admin). 4. Approx. time of occurrence (so logs can be correlated via the `X-Request-ID` that the backend emits). --- ### Appendix A — Feature map at a glance ``` Student Teacher Admin ───────────── ─────────────────── ───────────────────────────────────────── Dashboard Dashboard LMS Dashboard + Platform Dashboard Courses Courses Courses / Batches / Lessons / Library AI English Course Builder AI Prompt Editor AI IELTS Chapters AI Feedback Triage Adaptive path AI Workbench Exam review queue + detail Placement Assignments Exam template builder (IELTS + custom) Assignments Attendance Rubrics / Exam structures / Taxonomy Grades Students Grading queue + Score approval queue Attendance Library Reports (performance, corporate, gradebook) Timetable Timetable Admissions / Departments / Academic years Discussions Course Progress Roles / Authority matrix / Approval workflows Announcements Discussions Paymob + fees + payment record Messages Announcements Adaptive dashboard + per-student detail Journey Adaptive Settings White-label branding + Level mapping Profile Profile FAQ / Notification rules / Tickets Privacy Privacy Settings (LMS + platform) / Privacy ``` ### Appendix B — Keyboard shortcuts - **Sidebar collapse / expand** — `Ctrl/Cmd + B` - **Global search** — `Ctrl/Cmd + K` (where present) - **Submit form** — `Ctrl/Cmd + Enter` inside a form - **Close dialog / modal** — `Esc` ### Appendix C — Supported browsers - Chrome ≥ 115, Edge ≥ 115, Firefox ≥ 115, Safari ≥ 16. - Mobile Safari (iOS 16+) and Chrome Android are supported for the student portal. The admin portal is desktop-first.