full_encoach_platform/docs/USER_MANUAL.md

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
2. Student guide
3. Teacher guide
4. Admin guide
5. Privacy & language controls (all roles)
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 — /<role>/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.