yamen/full_encoach_platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add WORK_REPORT.md and USER_MANUAL.md
Some checks failed
CI / Frontend — lint + build + e2e (push) Has been cancelled
Details
CI / Backend — Odoo HttpCase (push) Has been cancelled
Details

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.

329
docs/WORK_REPORT.md Normal file
View File

@@ -0,0 +1,329 @@
# EnCoach — Work Report
**Period covered:** Recent hardening & delivery sprint (Phases 0 → 3 of the
improvement roadmap).
**Repository of record:** `https://git.albousalh.com/yamen/full_encoach_platform`
**Primary branch:** `main` (= current `v4` tip, commit `93c530ee`).
This report summarizes what was built, fixed, and documented in the last few
days. It's organized by phase so each block maps 1:1 to the roadmap items and
the commits that shipped them.
---
## Table of contents
- [Executive summary](#executive-summary)
- [What shipped — by phase](#what-shipped--by-phase)
- [Phase 0 — Platform safety & operations](#phase-0--platform-safety--operations)
- [Phase 1 — Exam correctness & data provenance](#phase-1--exam-correctness--data-provenance)
- [Phase 2 — Performance & observability](#phase-2--performance--observability)
- [Phase 3 — Human-in-the-loop, compliance, i18n, a11y, CI](#phase-3--human-in-the-loop-compliance-i18n-a11y-ci)
- [Branding update](#branding-update)
- [Repository migration](#repository-migration)
- [Commits landed in this sprint](#commits-landed-in-this-sprint)
- [Verification results](#verification-results)
- [Known gaps & deferred items](#known-gaps--deferred-items)
- [Operator checklist for production](#operator-checklist-for-production)
---
## Executive summary
| Area | Before | After |
| -------------------------- | -------------------------------------------- | ----------------------------------------------------------------------- |
| Duplicate exam models | Two `student.attempt` models in two modules | Single canonical `encoach.student.attempt` in `encoach_scoring` |
| Auth on AI routes | Public in places | `@jwt_required` on every AI / coach endpoint |
| Health check | None | `GET /api/health` + `GET /api/health/ready` (DB + LLM probes) |
| LLM resilience | Hangs possible | `request_timeout=30s` on OpenAI calls |
| Exam submit | Straight to graded | QualityChecker + IeltsValidator → `pending_review` gate |
| RAG metadata | Missing entity/course/subject | Full provenance on every embedding + chunking for large passages |
| Question provenance | Anonymous | `model`, `prompt_hash`, `log_id` stamped on every `encoach.question` |
| LLM output validation | Raw JSON hope-for-the-best | Schema validation before DB insert |
| Response envelope | Inconsistent across controllers | `{items,total,page,size}` everywhere |
| Reports | Python loops over thousands of rows | SQL `read_group` aggregates |
| Payments | Mocked Paymob | Real Accept flow + HMAC-SHA512 webhook verification |
| JWT | Single access token only | Refresh tokens + revocation table |
| Frontend bundle | Monolithic | `React.lazy` + Vite `manualChunks` (radix/charts/icons/forms split) |
| TypeScript errors | 181 | 0 |
| i18n | Hard-coded English | `i18next` + en/ar locales + RTL auto-switch + LanguageToggle |
| Exam review | No human review step | `pending_review → publish` workflow + admin UI |
| AI prompts | Buried in Python constants | `encoach.ai.prompt` versioned templates + admin editor + render preview |
| Student feedback on AI | None | Thumbs up/down → `encoach.ai.feedback` + admin triage |
| GDPR | None | `/api/gdpr/export` + `/api/gdpr/delete` + Privacy Center page |
| Dark mode | Partial | Full `ThemeProvider` + toggle + chart tokens |
| Accessibility | Dialog warnings | `DialogDescription` on every `DialogContent` |
| CI | None | GitHub Actions: frontend (tsc, lint, build, Playwright) + backend Odoo |
| Documentation | Scattered | §21 Hardening Release in `PROJECT_SUMMARY.md` + 4 ADRs |
---
## What shipped — by phase
### Phase 0 — Platform safety & operations
Goal: make the platform *safe to run* before adding features.
1. **Merged duplicate exam models.** `encoach_scoring` is now the single home
for `encoach.student.attempt` and `encoach.student.answer`; the stale
copies in `encoach_exam_template` were deleted along with the duplicate
`/api/exam/*` controllers.
2. **Added `@jwt_required` to every AI / coach route** so no AI endpoint is
reachable without an authenticated token.
3. **Added health endpoints**
- `GET /api/health` — liveness.
- `GET /api/health/ready` — readiness (DB ping + LLM reachability).
4. **Hardened OpenAI calls** with `request_timeout=30s` to prevent hung
workers on flaky provider responses.
5. **Gated `seed_demo_data.py` raw SQL** behind an explicit
`ENCOACH_SEED_DEMO=1` env flag so a stray run in production cannot
clobber real data.
6. **Fixed `docker-compose.yml`** and shipped `odoo-docker.conf` so the
container-local run works out of the box.
7. **Published `/logo.svg`** as a deployable asset (later superseded by the
project-manager PNG — see [Branding update](#branding-update)).
8. **Promoted a canonical `cefr_mapper`** to `encoach_ai.services.cefr_mapper`
(no more two copies drifting).
9. **JWT cache TTL = 30s** with an invalidation hook on user mutations so
role/entity changes propagate within half a minute.
### Phase 1 — Exam correctness & data provenance
Goal: make every AI-generated item *trustworthy and traceable*.
1. **QualityChecker + IeltsValidator wired into exam submit.** Submitted
attempts now pass through a validation layer and are parked in
`pending_review` if anything fails IELTS rubric / quality rules, instead
of being scored blind.
2. **Populated RAG metadata** on every `encoach.vector.embedding` record:
`course_id`, `subject_id`, `entity_id`, and taxonomy tags. Queries can
now be scoped per tenant / per skill.
3. **Chunking pipeline** for content > 2000 chars keeps embeddings within
model limits and preserves passage locality.
4. **Provenance fields on `encoach.question`**: `ai_model`, `prompt_hash`,
`log_id` — so any item can be traced back to the exact prompt + run
that produced it.
5. **Schema validation of LLM output** before DB insert (jsonschema-style).
Malformed JSON no longer reaches storage.
6. **Response envelope unified** to `{items, total, page, size}` across all
controllers.
7. **Approval reject rollback** now uses a PG savepoint so a partial
failure during rejection leaves no orphaned rows.
8. **Ticket notifications** fire on status and assignee change.
9. **`new_project/` retired.** `backend/` is declared canonical;
`new_project/DEPRECATED.md` carries the redirect notice.
### Phase 2 — Performance & observability
Goal: make the platform *fast and measurable*.
1. **Reports use SQL `read_group`** instead of Python loops. The admin
Reports pages no longer scan tens of thousands of attempt rows in
Python.
2. **`X-Request-ID` middleware + structured JSON logs** so a single
request can be traced end-to-end across controllers.
3. **Prometheus-style counters** (basic in-process) exposed through the new
`encoach_api` `openapi.py` controller, which also exports a live
OpenAPI spec by scanning `@http.route` decorators at runtime.
4. **In-process caching** for hot reports and the AI narrative endpoint,
with a Redis-ready seam.
5. **Paymob Accept integration** — the full 3-step flow (auth → order →
payment key) plus an HMAC-SHA512-verified webhook endpoint that
updates `encoach.paymob.order` atomically. Credentials come from
`ir.config_parameter`.
6. **JWT refresh tokens** with a revocation table and auto-refresh on the
frontend API client.
7. **Composite DB indexes** on the hottest report / ticket / attempt paths.
8. **React.lazy + Vite `manualChunks`** split `vendor-radix`,
`vendor-charts`, `vendor-icons`, `vendor-forms`, `vendor-react`, and
`vendor-query` into their own bundles.
9. **Fixed all 181 TypeScript errors.** `npx tsc --noEmit -p
tsconfig.app.json` now passes cleanly.
### Phase 3 — Human-in-the-loop, compliance, i18n, a11y, CI
Goal: make the platform *professional and defensible*.
1. **i18n.** `i18next` + language detector + en/ar locales + RTL
auto-switch + `LanguageToggle` component wired into both role and
admin layouts.
2. **GDPR compliance.** `/api/gdpr/export` returns a JSON snapshot of the
caller's personal data. `/api/gdpr/delete` anonymizes PII, nulls
logs, deactivates the account, creates an
`encoach.gdpr.erasure.request` tombstone, and refuses admin
self-erasure. A new `PrivacyCenter` page in the student / teacher /
admin portals exposes both actions.
3. **Human-in-the-loop exam review.** `pending_review → publish`
workflow, backed by a new `review_workflow.py` controller and two new
admin pages: `ExamReviewQueue` and `ExamReviewDetail`.
4. **AI prompt management.** New `encoach.ai.prompt` model with
versioning ("one active row per key"), REST endpoints for list /
retrieve / create / activate / render-preview, and the
`AIPromptEditor` admin page.
5. **Student AI feedback loop.** `encoach.ai.feedback` with upsert
semantics per `(user, subject_type, subject_id)`, reusable
`AIFeedbackButtons` component, and the `AIFeedbackTriage` admin page
with status filters and resolve actions.
6. **Dark mode** fully wired: `ThemeProvider` from `next-themes`,
`ThemeToggle`, and chart color tokens that follow the theme.
7. **Accessibility.** `DialogDescription` added to every
`DialogContent`, fixing the Radix a11y warning across the app.
8. **CI scaffolding.** `.github/workflows/ci.yml` runs two jobs on every
push: *frontend* (tsc → lint → build → Playwright smoke) and
*backend* (Postgres 16 + `odoo:19 --test-enable --test-tags
encoach_api`).
9. **Onboarding consolidated.** Single root `README.md` plus four ADRs:
- ADR-0001 canonical directory layout
- ADR-0002 JWT refresh token flow
- ADR-0003 paginated response envelope
- ADR-0004 RAG metadata + chunking
10. **Dead code removed.** `ExamPage` marketing, `Index`, `ProfilePage`
import, and other legacy routes excised.
---
## Branding update
The project-manager-supplied `EnCoach` logo (icon + wordmark + tagline
"Unlock your potential with AI powered platform") now appears across:
- **Login page** — shown at `h-36 w-auto` so the wordmark and tagline are
legible.
- **Student / teacher sidebar** — small rounded icon when collapsed, full
wordmark at `h-14` when expanded.
- **Admin sidebar** — same collapsed / expanded behavior.
- **`og:image` meta** (social cards) — already pointed at
`/logo-icon.png`, so it picks up the new asset automatically.
The duplicated inline `<span>EnCoach</span>` text was removed from every
sidebar since the wordmark is now baked into the image.
Commit: `47d09a3c chore(branding): adopt project-manager EnCoach logo
across login and sidebars`.
---
## Repository migration
To consolidate the codebase into a single canonical repo for future work,
the entire monorepo was migrated to:
- **`https://git.albousalh.com/yamen/full_encoach_platform`**
Migration steps performed:
1. Added the new repo as the `origin` remote.
2. Pushed the current `v4` tip as `main` (default branch).
3. Pushed all six local branches: `v4`, `v3`, `frontend-v3`,
`full_stack_dev`, `feature/full-backend-v1`,
`feature/generation-page-ai-workflows`.
4. Pushed all tags (none existed locally).
5. Rebound `v4` upstream to `origin/v4`.
6. **Removed all seven prior remotes** from `.git/config`:
`backend-v3`, `frontend`, `frontend-v3`, `ip-origin`,
`mirror-monorepo`, `origin-backend`, `origin-frontend`.
The local checkout now has exactly one remote — `origin` → the new URL —
so any future `git push` / `git pull` goes there with no further config.
---
## Commits landed in this sprint
```
93c530ee chore(ci,docs): GitHub Actions, ADRs, README overhaul, §21 Hardening Release
e70a2854 feat(frontend): Phase 2/3 hardening release
dcf5ea69 feat(backend): Phase 2/3 hardening release
47d09a3c chore(branding): adopt project-manager EnCoach logo across login and sidebars
c016a522 feat(reports): replace mock Reports pages with real backend aggregates
d940db07 fix(config): align Configuration pages with platform logic
7f23127e chore(remotes,docs): rename remotes to match source-of-truth doctrine
7737f6de docs(summary): declare encoach_backend_v4 + encoach_frontend_v4 as repos of record
```
File-churn totals for the four hardening commits:
| Commit | Files changed | Lines + | Lines − |
| ----------------------- | ------------- | ------- | ------- |
| branding (logo) | 4 | +42 | −18 |
| backend hardening | 70 | +4 221 | −716 |
| frontend hardening | 75 | +3 722 | −546 |
| CI + docs + ADRs | 10 | +740 | −96 |
---
## Verification results
Ran before each commit and again after the final commit:
| Check | Result |
| ------------------------------------------------------ | ----------------------------------------- |
| `python -m compileall backend/custom_addons/encoach_*` | Pass, no syntax errors |
| `npx tsc --noEmit -p tsconfig.app.json` | Pass (0 errors, down from 181) |
| `npm run build` | Pass — 3.63 s, bundles split as expected |
| `python -m compileall seed_demo_data.py` | Pass |
| Playwright smoke (`test:e2e`) | 2 / 2 tests pass (login renders, root→/login) |
Frontend bundle profile after `manualChunks`:
```
vendor-charts 422.80 kB │ gzip: 112.73 kB
vendor-radix 318.60 kB │ gzip: 99.50 kB
index (app shell) 219.02 kB │ gzip: 65.36 kB
vendor-forms 88.31 kB │ gzip: 24.40 kB
vendor-icons 53.77 kB │ gzip: 9.83 kB
vendor-query 41.17 kB │ gzip: 12.23 kB
vendor-react 23.33 kB │ gzip: 8.60 kB
```
---
## Known gaps & deferred items
These were intentionally **not** addressed in this sprint to keep scope
bounded. Each has a clear next owner / next step.
- **P1.2 — `ir.rule` entity isolation + drop blanket `sudo()`.** Requires
a full `sudo()` audit across every module + coordinated frontend
changes. Deferred to a follow-up ticket.
- **AIFeedbackButtons inside `AiStudyCoach`.** The coach's response
currently lacks the `ai_log_id` that the feedback model keys on. The
reusable component ships, but wiring it into the coach is gated on a
small service change.
- **Redis cache backend.** The in-process cache ships; wiring it to Redis
is a config + deployment-time step and was deferred.
- **Paymob credentials.** `payment.paymob.api_key`,
`payment.paymob.integration_id`, `payment.paymob.hmac_secret`, and
`payment.paymob.iframe_id` must be set in `ir.config_parameter`
before checkout works. Left unset on purpose — no secrets in git.
- **Arabic translation coverage.** Core UI (nav, auth, privacy,
feedback, theme, common) is translated; deeper exam-builder strings
still fall through to English.
---
## Operator checklist for production
Before promoting to production, an operator should:
1. **Set Paymob credentials** in `ir.config_parameter`:
- `payment.paymob.api_key`
- `payment.paymob.integration_id`
- `payment.paymob.hmac_secret`
- `payment.paymob.iframe_id`
2. **Set the OpenAI key** in `ir.config_parameter` as `openai.api_key`
(or the matching env var on the container).
3. **Run migrations** for the new modules / models:
`encoach.ai.prompt`, `encoach.ai.feedback`,
`encoach.gdpr.erasure.request`, `encoach.paymob.order`,
`encoach.jwt.token` (refresh revocation).
4. **Verify health** from outside the container:
`curl https://<host>/api/health` → 200, and
`curl https://<host>/api/health/ready` → 200 or 503 with structured
reason.
5. **Pin the default-branch protection** on
`git.albousalh.com/yamen/full_encoach_platform` (`main`).
6. **Schedule the CI workflow** — first run happens automatically on the
next push.
7. **Smoke Playwright locally** one more time: `cd frontend && npm run
test:e2e` (requires browsers via `npm run test:e2e:install`).