devops/encoach_frontend_new_v2
1
0
Fork 0
Code Issues Pull Requests 4 Actions Packages Projects Releases Wiki Activity

feat(v3): restructure project + add complete frontend

Browse Source 
- Restructure: move backend from new_project/ to backend/
- Add full React/TypeScript frontend (37 pages, 17 services, 16 type defs, 11 query hooks)
- Add docs/ with SRS specs, user stories, and workflow documentation
- Update .gitignore for new directory layout

Workflows implemented:
  WF1 User Signup, WF2 Placement Test, WF3 Exam Configuration,
  WF4 General English Exam, WF5 Course Generation,
  WF6 Entity Student Onboarding, AI Course Generation,
  Adaptive Learning Engine UI, White-Label Branding, Score Release

Made-with: Cursor
This commit is contained in:
Yamen Ahmad
2026-04-10 17:26:42 +04:00
parent a3e12f62fa
commit f1c4953a63
731 changed files with 67205 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
docs/Developer Workflow Manual.txt Normal file
View File

@@ -0,0 +1,156 @@
# Developer Workflow Manual — EnCoach Backend & Frontend
## One-Time Setup (Do This Once)
**Step 1 — Clone the repositories**
```bash
git clone https://git.albousalh.com/devops/encoach_backend_new_v2.git
git clone https://git.albousalh.com/devops/encoach_frontend_new_v2.git
```
**Step 2 — Switch to the working branch**
```bash
cd encoach_backend_new_v2
git checkout full_stack_dev
cd ../encoach_frontend_new_v2
git checkout full_stack_dev
```
**Step 3 — Install the `tea` CLI (to open PRs from terminal)**
```bash
# macOS
brew install tea
# Or download directly:
# https://gitea.com/gitea/tea/releases
# Configure it (run once):
tea login add --name encoach --url https://git.albousalh.com --token YOUR_TOKEN
```
> To get your token: log in at `https://git.albousalh.com` → top-right avatar → Settings → Applications → Generate Token.
---
## Every Day — Starting Work
**Step 4 — Always pull the latest before coding**
```bash
git checkout full_stack_dev
git pull origin full_stack_dev
```
> This makes sure you have the latest code before making changes.
---
## Making Changes
**Step 5 — Make your code changes locally**
Work as normal in your editor. No restrictions on what you change.
**Step 6 — If you add a new Python package**, add it to `new_project/requirements.txt`:
```
openai>=1.50
your-new-package>=x.x
```
**Step 7 — If you add a new Odoo addon**, place it under `new_project/custom_addons/your_module/` and make sure:
- The `__manifest__.py` lists **all** modules you reference via `comodel_name=` in its `depends` list.
- Notify Talal — new addons need a one-time manual install on the server (see end of this doc).
---
## Pushing Your Work
**Step 8 — Stage and commit your changes**
```bash
git add .
git commit -m "Short description of what you changed"
```
**Step 9 — Push to your working branch**
```bash
git push origin full_stack_dev
```
**Step 10 — Open a Pull Request** (asks Talal for review/approval)
```bash
tea pr create \
--repo devops/encoach_backend_new_v2 \
--head full_stack_dev \
--base main \
--title "Brief title of your changes" \
--description "What you changed and why"
```
> For frontend, replace `encoach_backend_new_v2` with `encoach_frontend_new_v2`.
**Step 11 — Notify Talal** that a PR is waiting for his review.
---
## After Talal Approves & Merges
**Step 12 — Deployment is fully automatic.** You do not need to do anything on the server.
What happens behind the scenes:
1. Talal merges the PR on `https://git.albousalh.com`
2. The server detects the merge to `main`
3. The deploy script pulls the latest code
4. Docker rebuilds the image (if `Dockerfile` or `requirements.txt` changed — takes ~10–15 min; otherwise ~1 min)
5. The container restarts with the new code
**Step 13 — Verify it worked** by checking the live URL:
- Frontend: `http://5.189.151.117:3000`
- Backend API: `http://5.189.151.117:8069/api/login`
---
## Checking Logs If Something Goes Wrong
SSH into the server (ask Talal for credentials) and run:
```bash
# Backend logs
docker logs backend-v2-odoo --tail 50
# Frontend logs
docker logs encoach-frontend --tail 50
```
---
## Special Case: Adding a New Odoo Addon
New addons need a **one-time manual install** on the server (the database doesn't know about them yet). Tell Talal and he will run:
```bash
ssh root@5.189.151.117
docker stop backend-v2-odoo
docker run --rm \
--network backend-v2_default \
-v /opt/encoach/backend-v2/odoo-docker.conf:/etc/odoo/odoo.conf:ro \
-v /opt/encoach/backend-v2/new_project/custom_addons:/mnt/custom_addons:ro \
-v /opt/encoach/backend-v2/new_project/enterprise-19:/mnt/enterprise:ro \
-v /opt/encoach/backend-v2/new_project/openeducat_erp-19.0:/mnt/openeducat:ro \
-v odoo-web-data:/var/lib/odoo \
encoach-backend:latest \
odoo -c /etc/odoo/odoo.conf -d encoach_v2 -i your_new_module --stop-after-init
docker start backend-v2-odoo
```
> After the first install, all future deploys update it automatically.
---
## Quick Reference
| Action | Command |
|---|---|
| Pull latest | `git pull origin full_stack_dev` |
| Commit | `git add . && git commit -m "message"` |
| Push | `git push origin full_stack_dev` |
| Open PR (backend) | `tea pr create --repo devops/encoach_backend_new_v2 --head full_stack_dev --base main --title "..."` |
| Open PR (frontend) | `tea pr create --repo devops/encoach_frontend_new_v2 --head full_stack_dev --base main --title "..."` |
| View logs (backend) | `docker logs backend-v2-odoo --tail 50` |
| View logs (frontend) | `docker logs encoach-frontend --tail 50` |

2125
docs/ENCOACH_USER_STORIES.md Normal file
View File

File diff suppressed because it is too large Load Diff

2479
docs/ENCOACH_WORKFLOWS_BACKEND_SRS.md Normal file
View File

File diff suppressed because it is too large Load Diff

2109
docs/ENCOACH_WORKFLOWS_FRONTEND_SRS.md Normal file
View File

File diff suppressed because it is too large Load Diff

587
docs/encoach_workflows_v3.md Normal file
View File

@@ -0,0 +1,587 @@
**ENCOACH**
Platform Workflow Documentation
_Complete System Design - All 7 Workflows_
Version 3.0 - Revised per Client Feedback | April 2026
| **7 Workflows** | **4 IELTS Skills** | **2 AI Course Engines** | **30+ DB Tables** |
| --------------- | ------------------ | ----------------------- | ----------------- |
Encoach Product Team | Confidential
Document Date: April 2026
_Version 3.0 - Implements all client feedback from annotated document review and meeting transcript analysis_
# **Version History**
| **Version** | **Date** | **Changes** |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1.0 | April 2026 | Initial release: Signup, Placement Test, Exam Config, Course Generation, Adaptive Learning, DB Schema |
| 2.0 | April 2026 | Added Workflow 4: General English AI Course Generation. Added Workflow 5: AI IELTS Course Generation. Updated Executive Summary and Coverage Audit. |
| 3.0 | April 2026 | Client feedback implementation: platform scope broadened to general LMS engine. Entity Student Onboarding added (Section 10a). IELTS reframed as fixed template. Auto-save updated to 10 seconds. Score release gate added. QR code on result PDF. CAPTCHA added. Placement range preA1-C2. Adaptive engine scope clarified. DB additions: entity_id tag, entity_level_mapping, entities, results_release_mode. White-labelling principle added. |
# **1\. Executive Summary**
This document captures the complete system design, workflow architecture, and database specifications for the Encoach platform rebuild. Encoach is a specialized platform providing an LMS solution with built-in AI adaptive learning for English, Math, and IT. The platform prepares users for local exams (e.g. STEP) and international certifications (e.g. IELTS, IC3). The adaptive learning framework is designed to be expandable by subject. English and IELTS are the primary focus for the current build - Math and IT will be integrated in September 2026.
## **1.1 Workflow Coverage - Final Status**
| **#** | **Workflow** | **Status** | **Section** |
| ----- | ------------------------------------ | --------------- | ------------ |
| 1 | User Signup | Complete | Section 4 |
| 2 | Placement Test | Complete | Section 5 |
| 3 | IELTS / English Exam Generation | Complete | Sections 2-3 |
| 4 | General English AI Course Generation | Complete - v2.0 | Section 11 |
| 5 | AI IELTS Course Generation | Complete - v2.0 | Section 12 |
| 6 | Entity Student Onboarding | Added - v3.0 | Section 10a |
## **1.2 Platform Overview**
| **Component** | **Description** |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Target users | International exam takers, academic students, self-learners (individual and institutional) |
| Exam focus | International certifications (IELTS, TOEFL, STEP, IC3) and General English - extendable to Math, IT, and other domains |
| Learning model | Adaptive learning engine with teacher oversight - subject-agnostic, applies to all modules |
| Assessment | CAT-based placement + IELTS practice exam generation + subject-specific placement tests |
| Content types | PDF, Video, Audio, Interactive exercises, AI-generated |
| Course modes | Teacher-built modules + adaptive engine, or fully autonomous AI course |
| AI generation | General English: on-demand from CEFR taxonomy. IELTS: standards-validated pipeline |
| Architecture | Database-driven, skill-tagged, CEFR-calibrated content library. Entity-aware with white-label support. |
# **2\. IELTS Exam Configuration Workflow - Entity**
_IELTS is one exam template within the platform. Its structure (4 skills, part counts, question formats, time limits) is fixed by the Encoach team and cannot be modified by teachers or admins. Admins select the IELTS template to begin, then manage questions within the fixed structural slots. The goal is a preset library of international exam templates (IELTS, TOEFL, STEP, IC3) built into the platform. 16 steps across 5 phases._
## **2.1 Phase 1 - Exam Initialization**
| **Step** | **Action** | **Actor** | **DB Impact** |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------- |
| 1 | Select exam type: Academic or General Training | Teacher/Admin | Filter exam_type on all queries |
| 2 | Select target skill(s): Listening, Reading, Writing, Speaking | Teacher/Admin | Opens per-skill branches |
| 3 | Set exam properties: title, target band, difficulty, randomization | Teacher/Admin | Written to exams table |
| 4 | Select question assembly mode: Auto, Manual, or Hybrid - controls question selection within fixed structural slots only; does not change exam structure | Teacher/Admin | Governs Phase 3 logic |
## **2.2 Phase 2 - Per-Skill Configuration**
Each selected skill opens its own configuration branch. Listening: 4 parts, 40 questions, audio-linked. Reading: 3 passages (Academic) or 3 sections (General), 40 questions. Writing: Task 1 + Task 2, rubric-linked. Speaking: Parts 1-3, 11-14 minutes, rubric-linked.
## **2.3 Phase 3 - Database Query & Content Retrieval**
_Clarification: The IELTS exam structure (parts, sections, question counts per part) is fixed by the Encoach IELTS template and is not determined by the queries below. These queries select specific questions to fill the fixed structural slots._
- Build query per skill - parameters: exam_type, skill, difficulty, part, student_id
- Retrieve content pool - DB returns 3-5x more items than needed
- Apply content filters - exclude seen, flagged, retired items; apply topic diversity and difficulty curve
- Select final items - Auto: system picks; Manual: teacher handpicks; Hybrid: system suggests
## **2.4 Phase 4 - Assembly & Validation**
- Assemble exam object - metadata, sections, questions, answer keys, rubrics, media refs saved as draft
- Run validation checks - question count, media URLs, answer keys, no duplicates, rubrics, time spec
- Teacher review - Manual/Hybrid only; swap questions, reorder, replace passages
- Approve and publish - status: draft → published; assigned to student(s); locked for editing
## **2.5 Phase 5 - Student Delivery**
- Student access - exam in dashboard, briefing shown, session token created
- Timed session - each section has countdown, answers auto-saved every 10 seconds
- Scoring - Listening and Reading: auto-scored. Writing and Speaking: teacher queue or AI engine
- Results - band scores stored, per-question feedback, weak areas flagged, LMS materials recommended
## **2.6 Database Schema - Exam Tables**
| **Table** | **Key Fields** |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| passages | id, exam_type, section_num, topic_category, body_text, difficulty, status |
| audio_files | id, exam_type, part (1-4), context_type, topic, audio_url, transcript, difficulty |
| questions | id, skill, source_id, question_type, stem, options, correct_answer, marks |
| writing_prompts | id, exam_type, task, writing_type, prompt_text, visual_url, rubric_id, min_words |
| speaking_cards | id, part, topic, questions, bullet_points, linked_card_id, rubric_id, difficulty |
| exams | id, title, exam_type, assembly_mode, target_band, difficulty, status, created_by, results_release_mode ENUM(auto,manual_approval) |
| exam_sections | id, exam_id, skill, part_number, time_limit_sec, question_count, content_id |
| student_attempts | id, student_id, exam_id, started_at, status, listening/reading/writing/speaking_band, overall_band, entity_id FK nullable |
# **3\. General English Exam Generation Workflow**
_Template-based exam generation for non-IELTS students. Grading split: auto-score (L/R) vs rubric (W/S). Pass/fail threshold routes to real exam registration or training path. DB store runs on all paths._
## **3.1 Phase 1 - Exam Configuration**
- Select exam type: General English, IELTS Academic, or IELTS General Training
- Select skills and difficulty level (B1/B2/C1/C2)
- System pulls from template DB and builds exam
## **3.2 Phase 2 - Exam Session**
- Student takes exam - timed, answers auto-saved every 10 seconds
- Exam submitted - all responses locked, session closed
## **3.3 Phase 3 - Grading & Scoring**
- Auto-score Listening and Reading - compared against grading database instantly
- Rubric score Writing and Speaking - teacher queue or AI engine
- Calculate overall band score - weighted average, CEFR mapped, compared vs pass threshold
- Score release decision - if exam_type = official: results held pending entity admin approval before student can view. If exam_type = practice: results auto-released immediately. Controlled by results_release_mode field on the exams table.
- Show results to student - band per skill, overall, gap to target (once released)
## **3.4 Phase 4 - Result Routing**
_Pass / sufficient score: System proposes real exam registration. Student chooses to register now or continue studying. Payment and scheduling process if registering._
_Below threshold: System generates adaptive training path. Skill gap modules assigned. Course generation workflow initiated. Teacher notified._
Step 10 (DB store) runs on all paths - results always written to student_attempts.
## **3.5 Phase 5 - Store & Close**
- Results confirmed and saved - student notified. PDF report generated with embedded QR code linking to a public score verification page. QR code encodes: student_id, exam_id, score, issue_date, and a verification hash. Employers and institutions can scan to verify result authenticity.
- Return to dashboard - next recommended action shown
# **4\. User Signup Workflow - Individual**
_This section covers individual self-registration. For institutional/entity bulk student registration see Section 10a: Entity Student Onboarding. Password creation, role selection, and email verification enforced before wizard. Wizard captures goal, target band, study preference, and learning style. Account only fully activated after wizard completion._
## **4.1 Registration**
- Enter name, email, and password - minimum 8 characters, strength indicator shown. CAPTCHA verification required on form submission. Note: CAPTCHA applies to individual self-registration only - entity bulk-upload accounts bypass this step.
- Select role - Academic student, Self-learner, or Teacher
## **4.2 Email Verification**
- System sends 6-digit OTP and verification link - expires in 15 minutes
- Decision: verified? If not - resend (max 3 attempts) → loop back
- Email verified → account created with status: unactivated
## **4.3 Onboarding Wizard (4 Steps)**
- Goal: General English / IELTS Academic / IELTS General Training / TOEFL / STEP / Mathematics / IT / Other certification. List is dynamic - driven by available exam templates in the platform DB.
- Target and timeline: target band or level, exam date if known
- Study preference: hours per week, self-study or with teacher, learning style (visual/audio/reading/mixed)
- Placement test prompt: take now or skip. If skipped - system assigns default content at median difficulty (B1 level) with a persistent prompt to complete placement before any personalised course is generated. Adaptive engine begins with no prior ability estimate and calibrates from the first student interaction.
## **4.4 Account Activation**
- Account fully activated - all wizard data saved to student_profile
- Student reaches dashboard - initial recommendations driven by wizard responses
# **5\. Placement Test Workflow**
_4-dimension CAT-based test. Reading comprehension added as fourth dimension. Speaking AI-evaluated asynchronously. Learning path shown to student BEFORE payment. Payment is optional - not a blocker. Scope note: This workflow describes the English placement process. The same CAT engine applies to Math and IT - subject-specific question banks feed the same adaptive logic. Module selection determines which question bank is used._
## **5.1 Phase 1 - Test Generation**
- System generates placement test - pulls from General English DB, calibrated to preA1-C2 full CEFR range. CAT engine starts at median difficulty and adapts upward or downward to correctly place any student regardless of starting level.
- Student briefed - instructions shown, timer starts
## **5.2 Phase 2 - Four-Dimension Testing**
_Total placement test duration: 20-30 minutes. CAT engine terminates earlier if ability estimate reaches sufficient precision (SEM below 0.3)._
| **Dimension** | **Questions** | **Content** | **Scoring** |
| ------------- | -------------------- | ----------------------------------------------------------------------------------- | ------------------ |
| Grammar | ~30 MCQ | Tenses, articles, prepositions, clauses | Auto immediately |
| Vocabulary | ~20 items | Definition match, gap fill, collocations | Auto immediately |
| Reading | ~10 Q / 2 passages | General + academic: TF/NG, MCQ - passages progress easy to difficult within section | Auto immediately |
| Speaking | 3 prompts (optional) | Record 60-second responses | AI evaluates async |
## **5.3 Phase 3 - Scoring & CEFR Mapping**
- Auto-score all sections - Grammar, Vocabulary, Reading instantly; Speaking by AI
- Map score to CEFR - A1/A2/B1/B2/C1/C2 stored to student_profile
- Show results to student - CEFR level, score per dimension, gap to target band
## **5.4 Phase 4 - Learning Path Generation**
- Generate learning path - skill gaps, modules, resources, estimated duration
- Preview shown to student - course outline, what is included in the plan
## **5.5 Phase 5 - Payment & Access**
- Pay now - full subscription or one-time payment, complete access
- Free trial - limited access, upgrade prompt later
- Skip - dashboard access, prompted later
# **6\. Course Generation Workflow**
_IELTS practice exam acts as placement test. This workflow applies to both individual and entity (institutional) students. Individual student path: student triggers course generation independently, full result visibility, system auto-builds course structure from gap profile with no teacher input required. Entity student path: entity admin or assigned teacher configures and approves course structure; result visibility controlled by the institution. Adaptive engine sequences content dynamically after publish._
## **6.1 Phase 1 - Placement as Diagnostic**
| **Step** | **Action** | **Output** |
| -------- | ------------------------------------------- | ------------------------------------------------------------- |
| 1 | Student takes practice exam (first attempt) | is_placement = true flagged in DB |
| 2 | Collect raw results | Band scores per skill, per-question correctness, time-on-task |
| 3 | Derive CEFR level | Band 4.0-4.5=B1, 5.0-5.5=B2, 6.0-6.5=C1, 7.0+=C2 |
| 4 | Set target band | Stored to student_profile.target_band, default: current + 1.0 |
## **6.2 Phase 2 - Skill Gap Analysis**
- Rank skills by gap size - largest gap = highest priority
- Identify question-type weaknesses - error rate per type
- Identify topic weaknesses - group wrong answers by category
- Generate gap profile report - skill ranks, hours, recommended resource types
## **6.3 Phase 3 - Course Structure Configuration**
_Individual student path: system auto-generates course structure from gap profile - no teacher input required. Entity student path: entity admin or assigned teacher configures course structure and approves before publish._
- Set course properties - title, exam type, target band, duration, study hours per week
- Select skills - system pre-selects gap >= 1.0; teacher can override
- Set skill weightings - hours per skill informed by gap size
- Define progression model - Linear, Parallel, or Adaptive
## **6.4 Phase 4 - Module Builder**
Each selected skill becomes a section with focused learning modules. Teacher attaches resources (PDF, video, audio, exercise, AI-generated), adds practice exercises, and sets completion criteria per module.
## **6.5 Phase 5 - Delivery & Tracking**
- Publish and assign - status: draft → published
- Student works through modules - all interactions logged
- Adaptive progression - checkpoint fail triggers remedial resources
- Progress dashboard - teacher sees live scores, time, predicted band improvement
- Post-course - new IELTS practice exam assigned as post-test
# **7\. Adaptive Learning Model**
_Adaptive learning is an intelligence layer across every workflow and every subject module. The engine is subject-agnostic - the signals and decision logic are identical for English, Math, and IT. Only the content taxonomy and question bank differ per subject. It continuously reads performance signals and adjusts content, difficulty, and sequence in real time._
## **7.1 Impact on Workflows**
| **Workflow** | **Change** |
| -------------------- | ---------------------------------------------------------------------- |
| User Signup | +1 wizard step: learning style preference (visual/audio/reading/mixed) |
| Placement Test | Fixed question set → Computer Adaptive Test (CAT) using IRT |
| Course Generation | Static module sequence → engine-managed dynamic path |
| Exam Config | Question bank gains IRT difficulty parameters (a, b, c values) |
| General English Exam | Post-exam training path → adaptive, not static |
## **7.2 Engine Signals & Decisions**
Signals read: quiz scores, error rate, retry count, time on task, video completion, study time patterns, module completion, band delta, past attempt history, CAT placement results.
Decisions made: next content to serve, difficulty adjustment (harder/easier/same), resource type to match learning style, micro-lesson insertion if stuck 2+ times, module skip if 95%+ score, teacher alert if no progress 3+ days.
## **7.3 Implementation Phases**
| **Phase** | **Scope** | **Complexity** |
| --------- | -------------------------------------------------------------- | -------------- |
| 1 - MVP | Rule-based engine. Teacher sets explicit thresholds. No ML. | Low |
| 2 | IRT-based CAT placement. Question bank calibrated. | Medium |
| 3 | Collaborative filter on student ability model data. | High |
| 4 | Full ML: dropout risk, optimal study time, next best question. | Very High |
# **8\. Key Design Principles**
## **8.1 Exam type is always the root parameter**
Academic vs General Training must be the first decision in any exam or course workflow. It gates all downstream content queries.
## **8.2 Learning path shown before payment**
The student must see their personalised course plan before any payment prompt. Showing payment before value is a conversion anti-pattern.
## **8.3 Teacher as supervisor, not builder**
In the adaptive model the teacher sets rules and reviews anomalies. The engine handles sequencing. This is a fundamental shift from the traditional LMS model.
## **8.4 All results stored on all paths**
Every exam attempt - regardless of pass or fail - is written to student_attempts. Required for longitudinal tracking, adaptive calibration, and improvement reporting.
## **8.5 Shared content database**
The exam and course workflows share the same content tables. Content is never duplicated - referenced from different contexts. One update affects both systems.
## **8.6 IELTS Band to CEFR Mapping**
| **IELTS Band** | **CEFR Level** |
| -------------- | ------------------------------------------------ |
| 4.0 - 4.5 | B1 - Basic academic English |
| 5.0 - 5.5 | B2 - Modest competence, noticeable imperfections |
| 6.0 - 6.5 | C1 - Effective operational proficiency |
| 7.0 - 7.5 | C2 - Good operational command |
| 8.0 - 9.0 | C2+ - Very good to expert user |
## **8.7 White-labelling support**
The platform supports institutional white-labelling. Each entity (university, school, corporate) can have a custom logo, colour scheme, and subdomain. Branding parameters are stored at entity level and applied to all student-facing pages when a student is linked to that entity. This does not affect workflow logic - only the front-end presentation layer.
# **9\. Complete Database Table Overview**
## **9.1 Content Tables**
- passages - reading passage content with metadata
- audio_files - listening audio with transcripts and part tagging
- writing_prompts - Task 1 and Task 2 prompts with rubric links
- speaking_cards - Part 1/2/3 cards with linked question sets
- questions - all auto-scoreable questions across all skills
- rubrics - scoring criteria for Writing and Speaking
## **9.2 Exam Tables**
- exams - exam configuration and metadata, includes results_release_mode ENUM(auto, manual_approval)
- exam_sections - skill sections within an exam
- exam_questions - question assignments to exam sections
- exam_assignments - student-to-exam assignments with access windows
## **9.3 User & Profile Tables**
- users - authentication and basic identity, includes entity_id FK (nullable), first_login BOOL, account_source ENUM
- student_profiles - CEFR level, placement, target band, learning style
- gap_profiles - generated gap analysis per placement attempt
## **9.4 Course Tables**
- courses - course configuration and assignment
- course_sections - per-skill sections within a course
- course_modules - individual learning units within sections
- resources - all learning resource files and metadata (includes ai_generated type)
- module_resources - resource assignments to modules
## **9.5 Progress & Results Tables**
- student_attempts - all exam attempt records with band scores, includes entity_id FK (nullable)
- student_answers - per-question student responses
- student_progress - module and resource completion tracking
- scores - final band scores per attempt and skill
- feedback - per-question feedback from teacher or AI
## **9.6 Adaptive Learning Tables**
- student_ability_model - live IRT ability estimate per skill
- cat_sessions - Computer Adaptive Test session logs
- adaptive_events - all engine signal and decision events
- adaptive_paths - current module queue per student
## **9.7 Entity & Institutional Tables (v3.0 additions)**
- entities - id, name, type ENUM(university, school, corporate, government), logo_url, white_label_domain, results_release_mode, created_at
- entity_level_mapping - entity_id, min_score, max_score, internal_level_name, cefr_equivalent. Allows each institution to map platform CEFR scores to their own grading system (e.g. UTAS Level 1/2/3/High Flyer).
_Data isolation rule: All student_attempts, student_progress, gap_profiles, and scores records include entity_id FK (nullable). entity_id=null means individual student. entity_id=X means linked to that institution. Results release and data visibility depend on this field. One shared database - never separate databases per entity._
# **10\. Appendix - Quick Reference**
## **10.1 IELTS Question Type Inventory**
| **Skill** | **Question Types** |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Listening | MCQ, Form completion, Note completion, Map/diagram labelling, Matching, Short answer, Summary completion |
| Reading | True/False/Not Given (TFNG), Yes/No/Not Given (YNNG), Heading matching, MCQ, Gap fill, Summary completion, Matching features, Short answer |
| Writing | Descriptive/Analytical (Academic T1), Formal/Semi-formal/Informal letter (General T1), Opinion/Discussion/Advantage-Disadvantage/Problem-Solution/Direct essay (T2 both) |
| Speaking | Familiar topic questions (P1), Cue card long turn (P2), Abstract discussion (P3) |
## **10.2 Assembly Mode Reference**
| **Mode** | **Description** | **Teacher Role** |
| -------- | ------------------------------------ | -------------------------------- |
| Auto | System builds entire exam from rules | Sets rules, approves result |
| Manual | Teacher handpicks every item | Handpicks from filtered pool |
| Hybrid | System suggests, teacher refines | Reviews and approves suggestions |
## **10.3 Progression Model Reference**
| **Model** | **Description** | **Engine Required** |
| --------- | ----------------------------------------------- | ------------------- |
| Linear | Fixed teacher-set module order | No |
| Parallel | All skill sections active simultaneously | No |
| Adaptive | Engine unlocks next module based on performance | Yes |
# **10a. Entity Student Onboarding Workflow**
_This workflow is entirely separate from individual User Signup (Section 4). It applies when a university, school, or institution (entity) registers students in bulk. Students registered via this workflow do not go through the standard onboarding wizard - they receive pre-created credentials and proceed directly to a placement test._
## **10a.1 Phase 1 - Admin Bulk Upload**
- Entity admin logs in to the admin dashboard and navigates to Student Management
- Admin uploads student list via CSV file or SIS (Student Information System) integration. Required fields: student name, institutional email, national ID number, student ID, enrolled programme (optional)
- System validates the upload - checks for duplicate emails, missing required fields, and format errors. Admin sees a validation report and can correct errors before confirming
- Admin confirms upload. System bulk-creates student accounts: username = institutional email, default password = national ID number. All accounts tagged with entity_id for data isolation and reporting
## **10a.2 Phase 2 - Credential Delivery**
- System sends each student a notification email: platform login URL, username (institutional email), temporary password (national ID), instructions to reset password on first login
- If the entity is SIS-integrated, the notification may be triggered automatically on student record creation
- Entity admin dashboard updates: all newly created accounts show status: pending first login
## **10a.3 Phase 3 - First Login & Password Reset**
- Student receives notification email and logs in with provided credentials
- System detects first_login = true and immediately prompts a mandatory password reset. Student must set a new password before proceeding. No onboarding wizard is shown to entity students.
- Account status updates to: active. Student taken directly to the dashboard
## **10a.4 Phase 4 - Placement Test (Entity Path)**
- Entity students are directed immediately to the placement test with no optional skip. Placement test is mandatory unless entity admin has pre-set the student's level (e.g. for Year 2 students bypassing initial placement)
- If the entity admin has configured a custom level mapping (entity_level_mapping table), placement results are mapped to the institution's internal level system in addition to CEFR
- Results stored with entity_id tag. Release of results to the student depends on the entity's results_release_mode setting (auto or manual_approval)
## **10a.5 Entity vs Individual Signup Comparison**
| **Aspect** | **Individual Signup (Section 4)** | **Entity Onboarding (Section 10a)** |
| ----------------- | --------------------------------- | ---------------------------------------- |
| Account creation | Student self-registers | Admin bulk uploads - system auto-creates |
| Default password | Student sets during signup | National ID - reset on first login |
| Onboarding wizard | 4-step wizard shown | No wizard - straight to placement test |
| CAPTCHA | Required | Not applicable - admin-initiated |
| Placement test | Optional - can skip | Mandatory (unless admin override) |
| Result visibility | Student sees immediately | Controlled by entity admin |
| Data tag | entity_id = null | entity_id = institution FK |
## **10a.6 New DB Fields for Entity Onboarding**
- users: +entity_id FK (nullable), +first_login BOOL, +account_source ENUM(self_registered, entity_bulk_upload)
- entities: id, name, type ENUM(university, school, corporate, government), logo_url, white_label_domain, results_release_mode ENUM(auto, manual_approval), created_at
- entity_level_mapping: entity_id, min_score, max_score, internal_level_name, cefr_equivalent
- student_attempts: +entity_id FK (nullable) - all attempt records tagged with institution context
# **11\. General English AI Course Generation Workflow**
_Unlike IELTS, General English has no fixed skill-part structure. Content is organised by CEFR level, grammar topic, vocabulary band, and skill area. The AI generates content from scratch using the student gap profile, then routes it through a quality gate before entering the course. The course builder is fully AI-autonomous - no teacher module build required._
## **11.1 What is different from IELTS course generation**
| **Dimension** | **IELTS Course (Workflow 12)** | **General English Course (Workflow 11)** |
| ------------------ | ------------------------------------------------ | ------------------------------------------------------ |
| Content structure | Fixed: 4 parts, 40 questions, part types defined | Flexible: grammar topic + CEFR level + skill area |
| AI content source | Generates to match strict IELTS format specs | Generates from CEFR taxonomy - open topic selection |
| Validation layers | 2 layers: automated standards + IELTS examiner | 1 layer: automated quality check + teacher review |
| Progression target | IELTS band score (4.0-9.0) | CEFR level (A1 → C2) |
| Course builder | Teacher-assisted or autonomous AI | Fully autonomous AI - no teacher module build required |
## **11.2 Phase 1 - Student Profile & Goal Setting**
- Read student placement profile - CEFR level, weak skills, learning style, target level
- Set course goal - target CEFR level confirmed (e.g. current B1, target B2)
## **11.3 Phase 2 - General English Content Taxonomy**
| **Dimension** | **Description** | **Examples** |
| ---------------------- | ---------------------------------------------------- | ------------------------------------------------------------------ |
| Grammar topics by CEFR | Specific grammar points calibrated to each level | A1: present simple; B2: conditionals, passive voice; C1: inversion |
| Vocabulary bands | Word frequency tiers and academic/topic sets | High-freq 1000-3000, Academic Word List, topic-specific sets |
| Skill areas | Core language skills each with distinct content type | Reading fluency, Writing practice, Speaking fluency, Listening |
| Topic categories | Real-world subject areas appropriate to CEFR level | Daily life, work, travel, technology, culture, environment |
## **11.4 Phase 3 - AI Content Generation Pipeline**
- AI receives generation brief - CEFR level, skill, grammar topic, vocab band, learning style preference
- AI generates per content type simultaneously:
- Step 5a - Reading passages with comprehension questions at target CEFR level
- Step 5b - Grammar exercises with explanations and worked examples
- Step 5c - Speaking prompts and contextual vocabulary sets
- AI auto-tags all generated content - CEFR level, grammar topic, vocab band, skill, resource type
## **11.5 Phase 4 - Quality Gate & DB Storage**
- Automated quality checks - readability score, CEFR calibration accuracy, grammar accuracy, length compliance
- Decision: Fail → AI regenerates with error details (max 3 attempts). Pass → proceeds to teacher review
- Teacher review - approve or edit content for accuracy, appropriateness, and student relevance
- Store to content DB - resources table, tagged, approved = true, available for all future courses
## **11.6 Phase 5 - Autonomous AI Course Delivery**
- AI builds course structure - sequences modules by CEFR progression without teacher involvement
- Three module types run in parallel: Grammar (explanation + exercises + worked examples), Skills (Reading/Writing/Speaking tasks at CEFR level), Vocabulary (contextual word learning + spaced repetition)
- Student works through course - adaptive engine adjusts difficulty, pace, and content type based on performance
- Decision: Level not yet achieved → AI generates next module content on demand. Level achieved → student levels up or course marked complete
- Progress report and next level path - CEFR gain shown, new placement level suggested, next course available
## **11.7 New DB Fields for General English AI**
| **Table** | **New Fields** |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| resources | +cefr_level ENUM, +grammar_topic VARCHAR, +vocab_band VARCHAR, +ai_generated BOOL, +approved BOOL |
| course_modules | +cefr_target ENUM, +auto_generated BOOL, +generation_brief JSONB |
| adaptive_paths | +source ENUM (placement/exam/ai_generated), +next_generation_brief JSONB |
| ai_generation_log | id, student_id, brief JSONB, attempts INT, final_resource_id UUID, approved_by UUID, created_at |
# **12\. AI IELTS Course Generation Workflow**
_IELTS content must conform to strict official standards: part structures, word counts, question type formats, and band-level rubrics. The AI generation pipeline has an additional IELTS standards validation layer that does not exist in Workflow 11. Covers both AI content creation AND fully autonomous course building._
## **12.1 The Critical Difference - Two Validation Layers**
_Workflow 11 - General English: ONE validation layer: automated readability/CEFR quality check → teacher review → DB store._
_Workflow 12 - AI IELTS: TWO validation layers: (1) IELTS format compliance + CEFR band calibration + answer key completeness → (2) IELTS-qualified teacher/examiner review → DB store. Content that fails layer 1 is returned to the AI with specific error details before it can reach human review._
## **12.2 Phase 1 - IELTS Gap Profile Input**
- Read IELTS placement results - band per skill, exam type (Academic or General Training), target band, weak question types
- AI ranks skills by gap size and sets generation priority order
## **12.3 Phase 2 - AI Content Generation Per IELTS Skill**
| **Skill** | **What AI Generates** | **IELTS Format Requirements** |
| --------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Listening | Audio scripts for Parts 1-4 + 10 questions per part | Part type (conversation/monologue), context, topic, dialect accuracy |
| Reading | Passages + 13-14 questions per passage | Academic (factual/analytical/argumentative) or General Training (everyday/work/general interest) |
| Writing | Task 1 + Task 2 prompts + model answers | Academic T1: visual data description. General T1: letter. Both T2: 5 essay types with correct structure |
| Speaking | Cue cards (P2) + question sets (P1 and P3) | P1: familiar topics. P2: bullet-point cue card. P3: abstract linked to P2 topic |
## **12.4 Phase 3 - IELTS Standards Validation (Unique to this Workflow)**
_This phase does not exist in Workflow 11. It is the critical gate that ensures all AI-generated content genuinely meets official IELTS specifications before human review._
- IELTS format compliance check - word count within official IELTS ranges per task/passage, correct part structure and question count, question type format matches IELTS specification
- CEFR band calibration check - readability score mapped to target band, difficulty verified against band descriptor
- Answer key and rubric completeness - all answer keys present for auto-scored items, Writing and Speaking rubrics linked with all four criteria
- Decision: Fail → AI revises with specific error details and returns to Phase 2. Pass → content proceeds to Phase 4
## **12.5 Phase 4 - IELTS Teacher / Examiner Review**
_Content source gate: AI-generated content → mandatory IELTS-qualified examiner review required. Content uploaded directly by an IELTS-certified entity → optional review, flagged for spot-check only._
IELTS teacher / examiner reviews content for: accuracy of topic and context, appropriateness of difficulty and language level, alignment with real IELTS exam conditions, cultural sensitivity and neutrality.
- Decision: Reject → flagged with notes, returns to Phase 2 for regeneration. Approve → content certified as IELTS-ready.
- Store to IELTS content DB - passages, audio scripts, prompts, speaking cards, questions stored with approved = true and ielts_certified = true
## **12.6 Phase 5 - Autonomous AI IELTS Course Builder & Delivery**
- AI builds IELTS course autonomously - sequences modules from gap profile without requiring teacher to manually build modules
- Four skill learning paths run in parallel: Writing path (T1 + T2 with model answers and rubric explanation), Reading path (3 passage sets with full question sets), Speaking path (Part 1/2/3 with cue cards and model responses), Listening path (Parts 1-4 with audio and question sets)
- Student works through AI course - adaptive engine adjusts difficulty and content type based on performance signals
- Decision: Target band not yet reached → AI generates harder content at next difficulty level. Target band reached → AI assigns full IELTS practice exam to confirm readiness.
- Band confirmed via practice exam - system proposes real IELTS exam registration
- Full progress report - band improvement per skill, modules completed, time spent, next recommended step
## **12.7 New DB Fields for AI IELTS**
| **Table** | **New Fields** |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| passages / audio_files / writing_prompts / speaking_cards | +ai_generated BOOL, +approved BOOL, +ielts_certified BOOL, +generation_brief JSONB, +validation_errors JSONB |
| questions | +ai_generated BOOL, +ielts_certified BOOL, +format_validated BOOL |
| ai_ielts_generation_log | id, skill, brief JSONB, format_check_result JSONB, band_check_result JSONB, examiner_id UUID, status, attempts INT |
| ielts_standards_checks | id, content_id, content_type, check_type, passed BOOL, error_detail JSONB, checked_at TIMESTAMP |
# **13\. Document Closure - v3.0 Final**
_All 6 workflows complete - document finalised. This version (v3.0) incorporates all client feedback from the annotated document review (Rose Fadi, 5 April 2026) and the meeting transcript (Talal Sharabi, Rose Fadi, Nasser ALDhahli, Yamena Ahmad). All 22 feedback items have been addressed._
## **13.1 Workflow Coverage**
| **#** | **Workflow** | **Status** | **Section** |
| ----- | ------------------------------------ | --------------------- | -------------- |
| 1 | User Signup - Individual | Complete | Section 4 |
| 2 | Placement Test | Complete | Section 5 |
| 3 | English / IELTS Exam Generation | Complete | Sections 2 + 3 |
| 4 | General English AI Course Generation | Complete | Section 11 |
| 5 | AI IELTS Course Generation | Complete | Section 12 |
| 6 | Entity Student Onboarding | Complete - added v3.0 | Section 10a |
## **13.2 Recommended Next Steps**
- Validate all database schemas with the backend architecture team
- Build Phase 1 adaptive engine (rule-based) - no ML required for v2
- Calibrate the question bank with IRT parameters for CAT placement
- Design the content management workflow for teachers uploading and tagging resources
- Define the AI prompt engineering standards for Workflows 11 and 12 content generation
- Recruit IELTS-qualified examiners for the Workflow 12 content review gate
- Implement entity_level_mapping configuration interface for institutional clients
- Build the admin score release approval interface for official exam results