diff --git a/docs/USER_MANUAL.md b/docs/USER_MANUAL.md new file mode 100644 index 00000000..cf1b83b8 --- /dev/null +++ b/docs/USER_MANUAL.md @@ -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 — `//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. diff --git a/docs/WORK_REPORT.md b/docs/WORK_REPORT.md new file mode 100644 index 00000000..061b61d8 --- /dev/null +++ b/docs/WORK_REPORT.md @@ -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 `EnCoach` 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:///api/health` → 200, and + `curl https:///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`).