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

docs: add WORK_REPORT.md and USER_MANUAL.md

Browse Source 
- docs/WORK_REPORT.md: recap of the Phase 0/1/2/3 hardening sprint —
  what shipped per phase, branding update, repo migration to the new
  full_encoach_platform repo, per-commit file-churn, verification
  results (tsc, build, Playwright), known gaps, and an operator
  checklist for production promotion.
- docs/USER_MANUAL.md: end-user guide for every role (Student, Teacher,
  Admin, Corporate, Agent, Developer). Walks through every portal URL,
  the AI coach / IELTS / adaptive flows, human-in-the-loop exam review,
  AI prompt editor, feedback triage, GDPR Privacy Center, language +
  theme toggles, and troubleshooting.

Made-with: Cursor
This commit is contained in:
Yamen Ahmad
2026-04-19 14:41:19 +04:00
parent 93c530eef2
commit 6712d1d551
2 changed files with 962 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

633
docs/USER_MANUAL.md Normal file
View File

@@ -0,0 +1,633 @@
# 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.