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](#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 — `/<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.