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

feat: initial backend codebase — EnCoach v3

Browse Source 
Complete Odoo 19 backend with 25 custom addons:
- encoach_core: user/entity/role management
- encoach_api: REST API + JWT auth
- encoach_ai: OpenAI integration, AI settings, generation
- encoach_ai_course: AI-powered English & IELTS course generation
- encoach_exam_template/session: exam creation, structures, sessions
- encoach_scoring: AI auto-grading + manual approval
- encoach_vector: pgvector RAG integration
- encoach_adaptive: adaptive learning engine
- encoach_placement: placement testing
- encoach_taxonomy/resources: content taxonomy & resource management
- Plus 14 more modules for courses, branding, portal, etc.

Includes docs: user guide, generation report, developer workflow.

Made-with: Cursor
This commit is contained in:
Yamen Ahmad
2026-04-11 15:44:20 +04:00
commit 982d4bca30
371 changed files with 35211 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

190
docs/06-All-Credentials-Inventory.md Normal file
View File

@@ -0,0 +1,190 @@
# EnCoach - Complete Credentials Inventory
**Extracted From:** Cloud Run service environment variables (plaintext)
**Date:** March 8, 2026
> **IMPORTANT:** All credentials below were found stored as plaintext environment variables
> in Cloud Run service configurations. They are NOT in Secret Manager, NOT in .env files,
> and NOT in the code repos. They were set directly during deployment.
---
## 1. AI Service Keys
| Variable | Value | Service | Used By |
|---|---|---|---|
| `OPENAI_API_KEY` | `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` | OpenAI (GPT-4o, GPT-3.5) | ielts-be (prod + staging) |
| `AWS_ACCESS_KEY_ID` | `AKIAXXT434IN3J7YQQ66` | AWS Polly (TTS) | ielts-be (prod + staging) |
| `AWS_SECRET_ACCESS_KEY` | `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` | AWS Polly (TTS) | ielts-be (prod + staging) |
| `ELAI_TOKEN` | `KtzxETdcZesZtwl7JKiYQapRvp0b4zMG` | ELAI (avatar videos) | ielts-be (prod + staging) |
| `GPT_ZERO_API_KEY` | `0195b9bb24c5439899f71230809c74af` | GPTZero (AI detection) | ielts-be (prod + staging) |
| `HEY_GEN_TOKEN` | `MjY4MDE0MjdjZmNhNDFmYTlhZGRkNmI3MGFlMzYwZDItMTY5NTExNzY3MA==` | HeyGen (legacy) | ielts-be (prod + staging) |
| `ELEVENLABS_API_KEY` | `sk_01190f3d023f6abe585d2bae06557cf4e4b9e1cf257d4732` | ElevenLabs (TTS) | ielts-be (staging only) |
| `ELEVENLABS_MODEL` | `eleven_multilingual_v2` | ElevenLabs model | ielts-be (staging only) |
| `TTS_PROVIDER` | `elevenlabs` | TTS provider selector | ielts-be (staging only) |
---
## 2. Database Credentials
| Variable | Value | Service | Used By |
|---|---|---|---|
| `MONGODB_URI` | `mongodb+srv://user:JKpFBymv0WLv3STj@encoach.3ydyg.mongodb.net/?retryWrites=true&w=majority&appName=EnCoach` | MongoDB Atlas | All services |
| `MONGODB_DB` (prod) | `production` | MongoDB database name | ielts-be, ielts-ui (prod) |
| `MONGODB_DB` (staging) | `staging` | MongoDB database name | ielts-be, ielts-ui (staging) |
| `DATABASE_HOST` | `34.77.91.43` | MySQL (CMS) | encoach-cms |
| `DATABASE_NAME` | `encoach` | MySQL database | encoach-cms |
| `DATABASE_USERNAME` | `root` | MySQL user | encoach-cms |
| `DATABASE_PASSWORD` | `VN*n1yVLxswU` | MySQL password | encoach-cms |
| `DATABASE_URL` | `jdbc:mysql://34.77.91.43:3306/` | MySQL connection | encoach-cms |
---
## 3. Authentication & Security Keys
| Variable | Value | Service | Used By |
|---|---|---|---|
| `JWT_SECRET_KEY` | `6e9c124ba92e8814719dcb0f21200c8aa4d0f119a994ac5e06eb90a366c83ab2` | Backend JWT | ielts-be |
| `JWT_TEST_TOKEN` | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0In0.Emrs2D3BmMP4b3zMjw0fJTPeyMwWEBDbxx2vvaWguO0` | Backend test JWT | ielts-be |
| `BACKEND_JWT` | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0In0.Emrs2D3BmMP4b3zMjw0fJTPeyMwWEBDbxx2vvaWguO0` | Frontend→Backend JWT | ielts-ui |
| `SECRET_COOKIE_PASSWORD` | `S2NrN2aBBYCpFpULvK2vDPFwsPbixAH6` | iron-session cookie | ielts-ui |
| `ADMIN_JWT_SECRET` | `aM9l2NPCbOlIBBfGfWAJAw==` | Strapi admin JWT | encoach-cms |
| `JWT_SECRET` | `hexTrI8hLY8k5syUSucXcg==` | Strapi public JWT | encoach-cms |
| `APP_KEYS` | `qLCKRYNICu/zsCYF566pEQ==,SbgGbzHLzVih3yY/bCvG9w==,xJ27/S+YudYyftTuqPRG8g==,dMDRY3LHbBOLavygMJIeNg==` | Strapi app keys | encoach-cms |
| `API_TOKEN_SALT` | `OWtKC1U80X18NIFBUpJV0A==` | Strapi API token salt | encoach-cms |
| `TRANSFER_TOKEN_SALT` | `qTWhsKJZK/Z2X0hDPtvCPA==` | Strapi transfer token | encoach-cms |
---
## 4. Firebase Credentials
### Production
| Variable | Value | Used By |
|---|---|---|
| `FIREBASE_PUBLIC_API_KEY` | `AIzaSyCdD3xqz5-25ZuRU_Tm2W7tBY9FtWCIfRU` | ielts-ui (prod) |
| `FIREBASE_AUTH_DOMAIN` | `storied-phalanx-349916.firebaseapp.com` | ielts-ui (prod) |
| `FIREBASE_STORAGE_BUCKET` | `storied-phalanx-349916.appspot.com` | ielts-ui, ielts-be (prod) |
| `FIREBASE_PROJECT_ID` | `storied-phalanx-349916` | ielts-ui, ielts-be (prod) |
| `FIREBASE_MESSAGING_SENDER_ID` | `785091389226` | ielts-ui (prod) |
| `FIREBASE_APP_ID` | `1:785091389226:web:77cab7f4990c76aa0d2053` | ielts-ui (prod) |
| `FIREBASE_CLIENT_EMAIL` | `tiago.ribeiro@ecrop.dev` | ielts-ui (prod) |
| `FIREBASE_CREDENTIALS` | `/app/firebase-configs/storied-phalanx-349916.json` | ielts-be (prod) |
| `FIREBASE_SCRYPT_B64_SIGNER_KEY` | `vbO3Xii2lajSeSkCstq3s/dCwpXP7J2YN9rP/KRreU2vGOT1fg+wzSuy1kIhBECqJHG82tmwAilSxLFFtNKVMA==` | ielts-ui, ielts-be (prod) |
| `FIREBASE_SCRYPT_B64_SALT_SEPARATOR` | `Bw==` | ielts-ui, ielts-be (prod) |
| `FIREBASE_SCRYPT_ROUNDS` | `8` | ielts-ui, ielts-be (prod) |
| `FIREBASE_SCRYPT_MEM_COST` | `14` | ielts-ui, ielts-be (prod) |
### Staging
| Variable | Value | Used By |
|---|---|---|
| `FIREBASE_PUBLIC_API_KEY` | `AIzaSyB1HDuvYOX18ZxpSgi2PmmVOaUu49CNYws` | ielts-ui (staging) |
| `FIREBASE_AUTH_DOMAIN` | `encoach-staging.firebaseapp.com` | ielts-ui (staging) |
| `FIREBASE_STORAGE_BUCKET` | `encoach-staging.appspot.com` | ielts-ui, ielts-be (staging) |
| `FIREBASE_PROJECT_ID` | `encoach-staging` | ielts-ui, ielts-be (staging) |
| `FIREBASE_MESSAGING_SENDER_ID` | `1078696515702` | ielts-ui (staging) |
| `FIREBASE_APP_ID` | `1:1078696515702:web:b8a5518dac09cf6e366757` | ielts-ui (staging) |
| `FIREBASE_CREDENTIALS` | `/app/firebase-configs/encoach-staging.json` | ielts-be (staging) |
| `FIREBASE_SCRYPT_B64_SIGNER_KEY` | `qjo/b5U5oNxA8o+PHFMZx/ZfG8ZQ7688zYmwMOcfZvVjOM6aHe4Jf270xgyrVArqLIQwFi7VkFnbysBjueMbVw==` | ielts-ui, ielts-be (staging) |
---
## 5. Payment Gateway Credentials
### Paymob (Production)
| Variable | Value | Used By |
|---|---|---|
| `PAYMOB_API_KEY` | `ZXlKaGJHY2lPaUpJVXpVeE1pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SmpiR0Z6Y3lJNklrMWxjbU5vWVc1MElpd2ljSEp2Wm1sc1pWOXdheUk2T1RFM0xDSnVZVzFsSWpvaWFXNXBkR2xoYkNKOS5HMnJTZXJ2WHR1UUEyNWVQN0tvTDBHaHJaUmM3VWx5RHhmV0huRDRPbkZpVExyV0xicnUzeVZSYXk2ZENqTnpXS1duWmJoZ2RYcUgwSGxnWkNUTi1aQQ==` | ielts-ui (prod) |
| `PAYMOB_PUBLIC_KEY` | `omn_pk_live_BkKVov5VSuLtTIqgcfya39ucEDcnX35l` | ielts-ui (prod) |
| `PAYMOB_SECRET_KEY` | `omn_sk_live_a669c50ebabb3d5c88135eee070a507258a7d10522214de89c123a4a5b25fd22` | ielts-ui (prod) |
| `PAYMOB_INTEGRATION_ID` | `1620` | ielts-ui (prod) |
### Paymob (Staging / Test)
| Variable | Value | Used By |
|---|---|---|
| `PAYMOB_PUBLIC_KEY` | `omn_pk_test_Oh9XcYe589i5FqXHLZ7yZGUkF2M8Vf55` | ielts-ui (staging) |
| `PAYMOB_SECRET_KEY` | `omn_sk_test_ee1e6e3f149b481f9b943334c680b7c3fa27e8f1800e111aae45cc829c92f8e5` | ielts-ui (staging) |
| `PAYMOB_INTEGRATION_ID` | `1540` | ielts-ui (staging) |
### Stripe (Landing Page)
| Variable | Value | Used By |
|---|---|---|
| `STRIPE_KEY` | `pk_test_51NzD5xFI67mXFum2XDMXiLu89SbCAMY5O0RnKjlU6XqyfboRVvFHI3f5OJHaxsrjjB7WqDYqN7Y3eF8mq3sF354F00l30L5GuJ` | encoach-landing-page |
| `STRIPE_SECRET` | `sk_test_51NzD5xFI67mXFum2Lzi2JtR8Th9zuA3CnoKKkAaOBiHmiHDQdGt7Pruj1Z89e4nF5eVNStL866twJLoVBUgfiaxZ00yqst8gkh` | encoach-landing-page |
| `STRIPE_PRICING_TABLE` | `prctbl_1O0hFcFI67mXFum2kEqiD57r` | encoach-landing-page |
---
## 6. Email / SMTP Credentials
| Variable | Value | Used By |
|---|---|---|
| `MAIL_USER` | `noreply@encoach.com` | ielts-ui |
| `MAIL_PASS` | `sovlwwwqvnenladl` | ielts-ui |
| `SMTP_HOST` | `smtp.gmail.com` | ielts-ui |
---
## 7. CMS / Strapi Integration
| Variable | Value | Used By |
|---|---|---|
| `STRAPI_URL` | `https://encoach-cms-zrwipjl2nq-ew.a.run.app` | encoach-landing-page |
| `STRAPI_TOKEN` | `1adf65151d6c8bf7491f4162d504dc9063ae750399fe8d4c841af20d2b3f8a3fbc6206ecb63bb9e9cbb9a00baac73a8547772ab0f16f0f7d04f4201f04ef72f9a2cb37fbadf5c347d8243a6733ac21589364e76b2fb5309386cb5aec52244f633b26d04faad5aca355df728200c86089d65e4162658a5b37ec1a6730d36fa383` | encoach-landing-page |
| `GCS_BUCKET_NAME` | `encoach-cms-media` | encoach-cms |
| `GCS_SERVICE_ACCOUNT` | *(base64-encoded GCP service account JSON with private key)* | encoach-cms |
---
## 8. Internal Service URLs
| Variable | Value | Used By |
|---|---|---|
| `BACKEND_URL` (prod) | `https://ielts-be-zrwipjl2nq-ew.a.run.app/api` | ielts-ui (prod) |
| `BACKEND_URL` (staging) | `https://ielts-be-zrwipjl2nq-zf.a.run.app/api` | ielts-ui (staging) |
| `WEBSITE_URL` | `https://encoach.com` | ielts-ui |
| `NEXT_PUBLIC_APP_URL` | `https://platform.encoach.com` | encoach-landing-page |
| `WEBHOOK_URL` | `https://encoach.com/api/stripe` | encoach-landing-page |
| `DATABASE_URL` | `jdbc:mysql://34.77.91.43:3306/` | encoach-cms |
---
## 9. Application Config (Non-Secret)
| Variable | Value | Used By |
|---|---|---|
| `ENVIRONMENT` (prod) | `platform` | ielts-ui (prod) |
| `ENVIRONMENT` (staging) | `staging` | ielts-ui (staging) |
| `PDF_VERSION` (prod) | `1.1.0` | ielts-ui (prod) |
| `PDF_VERSION` (staging) | `1.0.7` | ielts-ui (staging) |
| `EXCEL_VERSION` | `0.0.1` | ielts-ui |
| `HOST` | `0.0.0.0` | encoach-cms |
---
## Where Each Service Gets Its Keys
| Cloud Run Service | Region | Environment | Key Categories |
|---|---|---|---|
| **ielts-be** | europe-west1 | Production | AI keys, AWS, DB, Firebase, JWT |
| **ielts-be** | me-west1 | Staging | AI keys, AWS, DB, Firebase, JWT, ElevenLabs |
| **ielts-ui** | europe-west1 | Production | DB, Firebase, Paymob (live), SMTP, JWT |
| **ielts-ui** | us-central1 | Staging | DB, Firebase (staging), Paymob (test), SMTP, JWT |
| **encoach-frontend-staging** | me-central1 | Staging | DB, Firebase (staging), Paymob (test), SMTP, JWT |
| **encoach-cms** | europe-west1 | Production | MySQL, Strapi JWT, GCS service account |
| **encoach-landing-page** | europe-west1 | Production | Stripe (test), Strapi token |
---
## Notes
1. **Production and staging share the same OpenAI, AWS, ELAI, and GPTZero keys** — there is no separation of API keys between environments.
2. **Production and staging share the same MongoDB Atlas cluster** (`encoach.3ydyg.mongodb.net`) — only the database name differs (`production` vs `staging`).
3. **The Stripe keys on the landing page are test keys** (`pk_test_`, `sk_test_`) even in the production deployment.
4. **The `BACKEND_JWT` and `JWT_TEST_TOKEN` are identical** — the same test JWT is used for frontend-to-backend auth and for testing.
5. **The `GCS_SERVICE_ACCOUNT` in encoach-cms contains a full GCP service account private key** encoded in base64.
6. **The `FIREBASE_CLIENT_EMAIL` references `tiago.ribeiro@ecrop.dev`** — a developer's email from the previous development team.

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

957
docs/EnCoach-Platform-User-Guide.md Normal file
View File

@@ -0,0 +1,957 @@
# EnCoach Platform — Complete User Guide
**Version:** 4.0
**Last Updated:** April 11, 2026
---
## Table of Contents
1. [Getting Started](#1-getting-started)
2. [Student Guide](#2-student-guide)
3. [Teacher Guide](#3-teacher-guide)
4. [Admin Guide](#4-admin-guide)
5. [Common Features](#5-common-features)
6. [AI-Powered Features](#6-ai-powered-features)
7. [Exam Workflow (End-to-End)](#7-exam-workflow-end-to-end)
8. [Troubleshooting & FAQ](#8-troubleshooting--faq)
---
## 1. Getting Started
### 1.1 Accessing the Platform
| Environment | Frontend URL | Backend API |
|-------------|-------------|-------------|
| Local Dev | `http://localhost:8080` | `http://localhost:8069` |
| Production | `http://5.189.151.117:3000` | `http://5.189.151.117:8069` |
### 1.2 Logging In
1. Navigate to the platform URL
2. Enter your **Email** and **Password**
3. Click **Login**
4. You will be redirected to your role-specific dashboard:
- **Students** → `/student/dashboard`
- **Teachers** → `/teacher/dashboard`
- **Admins** → `/admin/dashboard`
- **Corporate/Agent** → `/admin/platform`
### 1.3 First-Time Users
- After registration and email verification, new users go through the **Onboarding Wizard** which collects learning goals and determines if a placement test is needed
- Students may be prompted to take a **Placement Test** to determine their CEFR level (A1–C2)
### 1.4 User Roles
| Role | Description | Access Level |
|------|-------------|--------------|
| **Student** | Learner enrolled in courses/exams | Own courses, exams, grades, progress |
| **Teacher** | Instructor managing courses | Own courses, student management, grading |
| **Admin** | Platform administrator | Full platform control, all modules |
| **Corporate** | Organization manager | Entity management, corporate stats |
| **Master Corporate** | Multi-org manager | Cross-entity management |
---
## 2. Student Guide
### 2.1 Dashboard
**Path:** `/student/dashboard`
Your home screen showing:
- Enrolled courses overview
- Upcoming exams and deadlines
- Recent grades
- Learning progress summary
- Quick links to active assignments
### 2.2 Courses
#### Browsing Courses
**Path:** `/student/courses`
- View all courses you are enrolled in
- See course progress percentage, teacher name, and schedule
- Click any course to view details
#### Course Detail
**Path:** `/student/courses/:id`
- View course description, syllabus, and materials
- Access course chapters and content
- Track your completion progress
#### Reading Chapter Content
**Path:** `/student/courses/:id/chapters/:chapterId`
- Read chapter materials (text, images, embedded media)
- Navigate between chapters using previous/next buttons
- Completion is tracked automatically
### 2.3 Adaptive Learning
#### Subject Selection
**Path:** `/student/subjects`
- Browse available subjects
- Select subjects you want to study
- Each subject has an adaptive learning path
#### Diagnostic Test
**Path:** `/student/diagnostic/:subjectId`
- Take a diagnostic test to assess your current level in a subject
- Results determine your personalized learning path
- Tests adapt to your responses in real time
#### Proficiency Profile
**Path:** `/student/proficiency/:subjectId`
- View your current proficiency level per subject
- See strengths and weaknesses across sub-skills
- Track how your proficiency changes over time
#### Learning Plan
**Path:** `/student/plan/:subjectId`
- View your personalized AI-generated learning plan
- See recommended topics in order of priority
- Track completion of each topic
#### Topic Learning
**Path:** `/student/topic/:topicId`
- Study a specific topic with curated materials
- Interactive exercises and practice questions
- AI-powered explanations and hints
### 2.4 Exams
#### Taking an Exam
**Path:** `/student/exam/:examId/session`
This is the full-screen exam delivery interface:
1. **Start** — Click "Begin Exam" to start the timer
2. **Navigate** — Use section tabs to switch between sections (Reading, Listening, Writing, Speaking)
3. **Answer** — Select answers for MCQ, type for fill-in-blank, write essays for writing tasks
4. **Auto-save** — Your answers are automatically saved every 30 seconds
5. **Review** — Click "Review" to see which questions are answered/unanswered
6. **Submit** — Click "Submit Exam" when done (or when time expires)
> **Important:** Once submitted, you cannot change your answers.
#### Exam Results
**Path:** `/student/exam/:examId/results`
- View your overall score and per-section breakdown
- See AI-generated feedback on each answer
- View correct answers for objective questions
- Check your IELTS band score (for IELTS exams)
#### Exam Status
**Path:** `/student/exam/:examId/status`
- Check if your exam is being graded
- See status: Submitted → Scoring → Released
- Some exams require manual approval before scores are visible
### 2.5 AI-Powered Courses
#### AI English Course
**Path:** `/student/course/ai-english/:courseId`
- AI-generated English course personalized to your level
- Interactive lessons covering grammar, vocabulary, reading, and writing
- Progress tracked automatically
#### AI IELTS Course
**Path:** `/student/course/ai-ielts/:courseId`
- IELTS-specific preparation course
- Covers all 4 IELTS skills: Reading, Listening, Writing, Speaking
- Practice with AI-generated IELTS-style questions
- Band score predictions
### 2.6 Placement Test
#### Briefing
**Path:** `/student/placement`
- Read instructions before starting the placement test
- Understand the test format and duration
#### Taking the Test
**Path:** `/student/placement/test`
- Adaptive test that determines your CEFR level
- Questions get harder or easier based on your answers
- Results determine which courses and content are recommended
#### Results
**Path:** `/student/placement/results`
- View your placement level (A1–C2)
- See skill-by-skill breakdown
- Recommended courses based on your level
### 2.7 Communication
#### Messages
**Path:** `/student/messages`
- Send and receive messages with teachers
- View conversation history
#### Discussions
**Path:** `/student/discussions`
- Participate in course discussion boards
- Ask questions and help classmates
- Teachers can respond to discussions
#### Announcements
**Path:** `/student/announcements`
- View announcements from teachers and administrators
- Important updates about courses, exams, and schedule changes
### 2.8 Progress & Grades
#### Grades
**Path:** `/student/grades`
- View all your grades across courses and exams
- Filter by course, date, or status
- Download grade reports
#### Learning Journey
**Path:** `/student/journey`
- Visual timeline of your learning progress
- Milestones achieved
- Skills gained over time
### 2.9 Account
#### Profile
**Path:** `/student/profile`
- Update personal information
- Change password
- Set notification preferences
---
## 3. Teacher Guide
### 3.1 Dashboard
**Path:** `/teacher/dashboard`
Your home screen showing:
- Active courses and student count
- Pending assignments to grade
- Upcoming schedule
- Quick stats on student performance
### 3.2 Course Management
#### My Courses
**Path:** `/teacher/courses`
- View all courses you teach
- See enrollment counts and completion rates
- Access course editing tools
#### Create a Course
**Path:** `/teacher/courses/new`
1. Fill in course title, description, and subject
2. Set enrollment limits and schedule
3. Add sections/chapters
4. Publish when ready
#### Edit a Course
**Path:** `/teacher/courses/:id/edit`
- Modify course settings, description, and materials
- Add/remove chapters and content
- Update enrollment settings
#### Course Chapters
**Path:** `/teacher/courses/:id/chapters`
- View and reorder chapters
- Add new chapters with content
- Set chapter visibility and prerequisites
#### Chapter Detail
**Path:** `/teacher/courses/:id/chapters/:chapterId`
- Edit chapter content (rich text editor)
- Add attachments, images, and videos
- Set chapter quizzes and exercises
#### AI Workbench
**Path:** `/teacher/courses/:id/workbench`
- Use AI to generate course content
- AI suggests materials, exercises, and assessments
- Edit and refine AI-generated content before publishing
- Batch optimize existing content
#### Course Progress
**Path:** `/teacher/course/:courseId/progress`
- View student progress across the course
- See per-chapter completion rates
- Identify students who are falling behind
### 3.3 Assignments
#### Assignment List
**Path:** `/teacher/assignments`
- View all assignments you've created
- Filter by course, status, or date
- See submission counts
#### Assignment Detail
**Path:** `/teacher/assignments/:id`
- View student submissions
- Grade assignments manually or with AI assistance
- Leave feedback on each submission
- Bulk grading tools
### 3.4 Student Management
#### My Students
**Path:** `/teacher/students`
- View all students across your courses
- See individual performance summaries
- Contact students directly
#### Attendance
**Path:** `/teacher/attendance`
- Record daily attendance
- View attendance history
- Generate attendance reports
### 3.5 Schedule
#### Timetable
**Path:** `/teacher/timetable`
- View your weekly teaching schedule
- See room assignments and time slots
- Sync with calendar
### 3.6 Communication
#### Discussions
**Path:** `/teacher/discussions`
- Manage course discussion boards
- Respond to student questions
- Pin important announcements
#### Announcements
**Path:** `/teacher/announcements`
- Create and publish announcements
- Target specific courses or all students
- Set announcement priority
### 3.7 Adaptive Learning Settings
**Path:** `/teacher/adaptive/settings`
- Configure adaptive learning parameters for your courses
- Set difficulty progression rules
- Customize AI behavior for student recommendations
### 3.8 Account
#### Profile
**Path:** `/teacher/profile`
- Update professional information
- Set office hours
- Manage notification settings
---
## 4. Admin Guide
### 4.1 Dashboards
#### LMS Dashboard
**Path:** `/admin/dashboard`
- Overview of all courses, students, teachers, and batches
- Charts: enrollment trends, completion rates, active users
- Quick actions to manage platform
#### Platform Dashboard
**Path:** `/admin/platform`
- Entity-level overview (for multi-organization setups)
- Revenue stats, ticket counts
- Cross-entity comparisons
### 4.2 Exam Management
#### Generation Page (AI-Powered)
**Path:** `/admin/generation`
The main exam creation tool. Create complete exams with AI:
1. **Fill Header** — Enter exam title, label, and select a structure
2. **Select Modules** — Choose from Reading, Listening, Writing, Speaking, Level, Industry
3. **Configure Per Module:**
- Timer (minutes)
- Difficulty level (A1–C2 CEFR tags)
- Access type (Private/Public)
- Approval workflow
- Grading system
- Shuffling toggle
4. **Reading Module:**
- Add passages (1–3+)
- AI generates passage text from a topic
- Select exercise types: Multiple Choice, Fill Blanks, Write Blanks, True/False, Paragraph Match
- Generate exercises from the passage
5. **Listening Module:**
- Add sections: Social Conversation, Social Monologue, Academic Discussion, Academic Monologue
- AI generates conversation/monologue context
- Generate audio (Text-to-Speech via ElevenLabs)
- Select exercise types
6. **Writing Module:**
- Add Task 1 (letter) and Task 2 (essay)
- AI generates task instructions
- Set word limits and marks
7. **Speaking Module:**
- Add Speaking 1, Speaking 2, Interactive Speaking
- AI generates examiner scripts
- Select avatar for video generation (Gia, Vadim, Orhan, Flora, Scarlett, Parker, Ethan)
- Generate video with AI avatar
8. **Submit:**
- "Submit for approval" — creates exam in draft status
- "Skip approval" — publishes immediately
#### Exam Structures
**Path:** `/admin/exam-structures`
- Create reusable exam structure templates
- Define which modules are included
- Set per-structure industry and entity
- Delete outdated structures
#### IELTS Exam Creation
**Path:** `/admin/exam/ielts/create` → `/admin/exam/ielts/:examId/skills` → `/admin/exam/ielts/:examId/content` → `/admin/exam/ielts/:examId/validate`
Step-by-step IELTS exam creation:
1. **Create** — Set title, template, entity
2. **Skills** — Configure skills (reading, listening, writing, speaking)
3. **Content Pool** — Auto-assemble questions from the content pool
4. **Validate** — Check all sections have enough questions before publishing
#### Custom Exam Creation
**Path:** `/admin/exam/custom/create`
- Create non-IELTS exams with flexible section structure
- Add sections with any skill type
- Assign questions manually or auto-assemble
#### Exams List
**Path:** `/admin/examsList`
- View all exams across the platform
- Filter by status, module, entity
- Quick actions: edit, delete, assign
#### Grading Queue
**Path:** `/admin/exam/:examId/grading`
- View submissions waiting for grading
- AI suggests grades for written/spoken answers
- Accept, modify, or override AI grades
- Submit final grades
#### Score Approval
**Path:** `/admin/scores/pending`
- Review scores pending approval
- Approve or reject score releases
- Bulk approval actions
#### Exam Sessions
**Path:** `/admin/exam-sessions`
- Manage institutional exam sessions
- Schedule exam dates and rooms
- Monitor active sessions
### 4.3 User Management
#### Users
**Path:** `/admin/users`
- List all platform users
- Filter by role (student, teacher, admin, corporate)
- Create, edit, or deactivate users
#### Roles & Permissions
**Path:** `/admin/roles-permissions`
- Define custom roles
- Assign permissions per role
- View permission matrix
#### User Roles
**Path:** `/admin/user-roles`
- Assign roles to specific users
- Bulk role assignment
#### Authority Matrix
**Path:** `/admin/authority-matrix`
- Define who can approve what
- Set multi-level approval chains
### 4.4 Academic Management
#### Students
**Path:** `/admin/students`
- Full student management
- View enrollments, grades, attendance
- Bulk student operations
#### Teachers
**Path:** `/admin/teachers`
- Manage teacher profiles
- Assign courses and batches
#### Courses
**Path:** `/admin/courses`
- All courses across the institution
- Create, edit, archive courses
#### Batches
**Path:** `/admin/batches`
- Group students into batches
- Assign batches to courses/exams
#### Timetable
**Path:** `/admin/timetable`
- Institution-wide schedule management
- Room and time slot allocation
#### Attendance
Managed through teacher interface; admin can view reports.
#### Gradebook
**Path:** `/admin/gradebook`
- Institution-wide grade overview
- Export grade reports
#### Marksheets
**Path:** `/admin/marksheets`
- Generate and print official marksheets
- Per-student or per-batch
### 4.5 LMS Content
#### Course Configuration
**Path:** `/admin/course/configure/:courseId`
- Advanced course settings
- Set prerequisites, completion rules
- Configure grading scheme
#### Module Builder
**Path:** `/admin/course/:courseId/modules`
- Build course modules and content
- Drag-and-drop module ordering
- AI-assisted content generation
#### Lessons
**Path:** `/admin/lessons`
- Manage individual lessons
- Schedule lessons across batches
### 4.6 Adaptive Learning
#### Taxonomy Manager
**Path:** `/admin/taxonomy`
- Manage subject taxonomies (subjects → topics → sub-topics)
- Set difficulty levels and prerequisites
- Configure adaptive progression rules
#### Resource Manager
**Path:** `/admin/resources`
- Upload and manage learning resources
- Link resources to topics
- Categorize by type (video, article, exercise, etc.)
#### Adaptive Dashboard
**Path:** `/admin/adaptive/dashboard`
- Overview of adaptive learning across the platform
- See which students are on track vs struggling
- System-wide learning analytics
#### Student Adaptive Detail
**Path:** `/admin/adaptive/student/:studentId`
- Deep dive into a specific student's adaptive path
- View learning events and signals
- Override AI recommendations if needed
### 4.7 AI Management
#### AI English Quality
**Path:** `/admin/ai-course/english/:courseId/quality`
- Review AI-generated English course content quality
- Approve or reject generated materials
- Edit content before publishing
#### AI English Taxonomy
**Path:** `/admin/ai-course/english/taxonomy`
- Manage the taxonomy that drives AI English course generation
- Add/edit topics and difficulty mappings
#### AI IELTS Validation
**Path:** `/admin/ai-course/ielts/:courseId/validation`
- Validate AI-generated IELTS content
- Ensure question quality and accuracy
- Approve for student access
### 4.8 Entity & Organization
#### Entities
**Path:** `/admin/entities`
- Manage organizations (schools, companies, etc.)
- Set entity-level settings
- View entity statistics
#### Level Mapping
**Path:** `/admin/entity/:entityId/level-mapping`
- Map CEFR levels to entity-specific levels
- Configure level thresholds
#### White-Label Branding
**Path:** `/admin/entity/:entityId/branding`
- Customize platform appearance per entity
- Upload logos, set colors
- Custom domain settings
#### Bulk Student Upload
**Path:** `/admin/entity/students/upload`
- Upload students via CSV/Excel
- Map columns to student fields
- Preview and confirm before import
#### Credential Dashboard
**Path:** `/admin/entity/students/credentials`
- Manage student login credentials
- Bulk password reset
- View credential status
### 4.9 Admissions
#### Admission List
**Path:** `/admin/admissions`
- View all admission applications
- Filter by status (pending, approved, rejected)
#### Admission Detail
**Path:** `/admin/admissions/:id`
- Review application details
- Approve or reject with comments
#### Admission Register
**Path:** `/admin/admission-register`
- Configure admission periods and requirements
- Set document requirements
- Manage admission quotas
### 4.10 Financial
#### Fees
**Path:** `/admin/fees`
- Manage fee structures
- View payment status per student
- Generate invoices
#### Payment Records
**Path:** `/admin/payment-record`
- View all payment transactions
- Filter by date, student, status
- Export payment reports
### 4.11 Training Modules
#### Vocabulary
**Path:** `/admin/training/vocabulary`
- Manage vocabulary content and exercises
- Create word lists by topic and level
#### Grammar
**Path:** `/admin/training/grammar`
- Manage grammar lessons and exercises
- Create grammar rules and practice sets
### 4.12 Configuration
#### Platform Settings
**Path:** `/admin/settings-platform`
- Global platform configuration
- API key management (OpenAI, ElevenLabs, AWS, etc.)
- System defaults
#### LMS Settings
**Path:** `/admin/settings`
- LMS-specific settings
- Grading policies
- Enrollment rules
#### Approval Workflows
**Path:** `/admin/approval-workflows` and `/admin/approval-config`
- Define approval steps for content, exams, scores
- Set required approvers per workflow
#### Notification Rules
**Path:** `/admin/notification-rules`
- Configure when and how notifications are sent
- Set triggers (new assignment, grade release, etc.)
- Choose channels (email, in-app, SMS)
#### FAQ Manager
**Path:** `/admin/faq`
- Create and manage FAQ entries
- Categorize by topic
- Publish to the public FAQ page
### 4.13 Support
#### Tickets
**Path:** `/admin/tickets`
- View support tickets from users
- Assign to team members
- Track resolution status
### 4.14 Reports & Analytics
#### Reports
**Path:** `/admin/reports`
- Generate institutional reports
- Student performance analytics
- Course effectiveness metrics
#### Student Performance
**Path:** `/admin/student-performance`
- Detailed student performance analysis
- Compare across batches and courses
- Export data
#### Corporate Stats
**Path:** `/admin/stats-corporate`
- Corporate-level analytics
- Multi-entity comparisons
- ROI metrics
---
## 5. Common Features
### 5.1 Public Pages
| Feature | URL | Description |
|---------|-----|-------------|
| FAQ | `/faq` | Browse frequently asked questions |
| Score Verification | `/verify/:hash` | Verify a certificate or score by unique hash |
| Admission Application | `/apply` | Public multi-step admission form |
| Password Reset | `/forgot-password` | Request a password reset email |
### 5.2 AI Features Available to All
- **AI Tip Banner** — contextual AI tips displayed on relevant pages
- **AI Search** — intelligent search across platform content
- **AI Study Coach** — personalized study recommendations (students)
- **AI Writing Helper** — real-time writing assistance (during exams/assignments)
- **AI Grade Explainer** — explains why you received a specific grade
---
## 6. AI-Powered Features
### 6.1 Content Generation (Admin)
| Feature | Module | What It Does |
|---------|--------|--------------|
| Passage Generation | Reading | AI creates reading passages at specified CEFR level and topic |
| Exercise Generation | Reading | AI creates MCQ, Fill Blanks, True/False, etc. from a passage |
| Context Generation | Listening | AI creates conversation/monologue transcripts |
| Audio Generation | Listening | Text-to-Speech converts transcripts to audio (ElevenLabs) |
| Instruction Generation | Writing | AI creates writing task instructions |
| Script Generation | Speaking | AI creates speaking exam scripts with examiner questions |
| Avatar Video | Speaking | AI generates video of an avatar delivering the speaking script |
| Course Content | Courses | AI generates lesson content, materials, and exercises |
| Material Suggestions | Workbench | AI suggests relevant learning materials for a topic |
### 6.2 Assessment (Teacher/Admin)
| Feature | What It Does |
|---------|--------------|
| AI Grading Suggestions | AI scores written and spoken answers with explanations |
| AI Batch Optimizer | Optimize multiple content items at once |
| AI Insights | Analytics and patterns in student performance |
### 6.3 Learning (Student)
| Feature | What It Does |
|---------|--------------|
| Adaptive Learning Path | AI adjusts content difficulty based on performance |
| AI Study Coach | Personalized study tips and recommendations |
| AI Writing Helper | Real-time writing feedback and suggestions |
| Gap Analysis | AI identifies knowledge gaps and generates targeted courses |
### 6.4 Supported AI Services
| Service | Provider | Used For |
|---------|----------|----------|
| GPT-4o | OpenAI | Content generation, grading, feedback |
| GPT-3.5 Turbo | OpenAI | Fast/lightweight generation tasks |
| ElevenLabs | ElevenLabs | Text-to-Speech (listening audio) |
| AWS Polly | Amazon | Alternative TTS provider |
| ELAI | ELAI.io | Avatar video generation (speaking) |
| GPTZero | GPTZero | AI content detection |
| Sentence Transformers | HuggingFace | Vector embeddings for RAG search |
---
## 7. Exam Workflow (End-to-End)
### Step 1: Admin Creates Exam
1. Go to `/admin/generation`
2. Enter exam title and select modules
3. Generate content with AI for each module
4. Submit for approval or publish directly
### Step 2: Admin Assigns Exam
1. Go to `/admin/examsList`
2. Select the exam
3. Assign to students or batches
4. Set access window (start/end dates)
### Step 3: Student Takes Exam
1. Student sees exam on `/student/dashboard`
2. Clicks to start → `/student/exam/:examId/session`
3. Answers questions within time limit
4. Submits exam
### Step 4: AI + Teacher Grading
1. Objective questions (MCQ, T/F) are auto-graded instantly
2. Subjective questions (writing, speaking) go to grading queue
3. Teacher views at `/admin/exam/:examId/grading`
4. AI suggests grades → teacher approves/modifies
5. Final grades are submitted
### Step 5: Score Approval (if configured)
1. Admin reviews scores at `/admin/scores/pending`
2. Approves or requests re-grading
3. Scores are released to students
### Step 6: Student Views Results
1. Student sees notification
2. Views results at `/student/exam/:examId/results`
3. Sees score breakdown, AI feedback, and correct answers
---
## 8. Troubleshooting & FAQ
### Q: I can't log in
- Check that your email and password are correct
- If you forgot your password, use `/forgot-password`
- Contact your admin if your account is deactivated
### Q: My exam score is not showing
- Scores may be pending teacher grading (check exam status)
- Scores may require admin approval before release
- Contact your teacher if it's been more than 48 hours
### Q: AI generation is not working
- Check that AI keys are configured in `/admin/settings-platform` (admin)
- Check the OpenAI API key is valid and has credits
- Check Odoo settings at `http://localhost:8069/odoo/settings` for EnCoach AI Services
### Q: I see "Access Denied" errors
- Your role may not have permission for that page
- Contact your admin to verify your role and permissions
- Log out and log back in to refresh your session
### Q: Audio/Video is not generating
- ElevenLabs API key is required for audio generation
- ELAI API key is required for avatar video generation
- Check these in the AI Settings page (admin)
### Q: How do I change my CEFR level?
- Take a diagnostic test at `/student/diagnostic/:subjectId`
- Or ask your teacher to manually adjust your level
---
*EnCoach Platform v4.0 — Built with Odoo 19, React 18, TypeScript, and AI*

225
docs/REPORT-Generation-Page-Implementation.md Normal file
View File

@@ -0,0 +1,225 @@
# Generation Page - Full Implementation Report
**Date:** April 11, 2026
**Branch:** `feature/generation-page-ai-workflows`
**Author:** Development Team
**Status:** Completed & Tested
---
## 1. Executive Summary
Rebuilt the **Generation Page** from a static placeholder into a fully functional, production-parity exam generation system. The page now matches the production version at `platform.encoach.com/generation` with real AI-powered content generation for all 4 IELTS modules (Reading, Listening, Writing, Speaking), plus Exam Structures CRUD and exam submission workflows.
**Key metrics:**
- 12 API endpoints created/enhanced
- 7 AI generation workflows fully operational
- 4 IELTS modules with per-module configuration
- End-to-end tested with real OpenAI API calls
---
## 2. What Was Done
### 2.1 Production Analysis
- Scraped and documented every feature of the production Generation page at `platform.encoach.com/generation`
- Created a complete feature map comparing production vs local implementation
- Identified all missing features across 6 categories
### 2.2 Frontend Changes
#### `GenerationPage.tsx` — Complete Rebuild (900+ lines)
**Before:** Static form with hardcoded structure options, no API calls, fake "success" on submit.
**After:** Full-featured exam generation wizard with:
- **Exam Header:** Title, Label, Exam Structure dropdown (API-driven)
- **6 Module Selection:** Reading, Listening, Writing, Speaking, Level, Industry — each with colored badges and visual feedback
- **Per-Module Common Config:**
- Timer (minutes)
- Difficulty tags (CEFR levels A1–C2, add/remove chips)
- Access Type (Private/Public)
- Entities dropdown
- Approval Workflow dropdown
- Rubric Criteria Groups & Criteria
- Grading System
- Total Marks (calculated)
- Shuffling toggle
- **Reading Module:**
- Multiple passages (add/remove)
- Per-passage collapsible settings: Category, Type, Divider
- AI Passage Generation: Topic, Difficulty, Word Count → Generate button → OpenAI
- 5 Exercise Types: Multiple Choice, Fill Blanks, Write Blanks, True/False, Paragraph Match
- Exercise setup with "Set Up Exercises" button
- Passage content card with Save/Discard/Edit controls
- **Listening Module:**
- 4 Section Types: Social Conversation, Social Monologue, Academic Discussion, Academic Monologue
- Per-section: Audio Context generation (AI), Audio generation (TTS via ElevenLabs)
- 5 Exercise Types: MCQ, Write Blanks (Questions/Fill/Form), True/False
- **Writing Module:**
- Task 1 / Task 2 support
- AI Instruction Generation with topic and difficulty
- Word Limit, Marks fields
- Save/Edit/Graded controls
- **Speaking Module:**
- Speaking 1 / Speaking 2 / Interactive Speaking parts
- AI Script Generation with dual topic inputs
- Avatar Video Generation with 7 avatars (Gia, Vadim, Orhan, Flora, Scarlett, Parker, Ethan)
- Marks field per part
- **Action Buttons:**
- "Submit module as exam for approval" → creates exam in DB with `draft` status
- "Submit module as exam and skip approval" → creates with `published` status
- "Preview module" (placeholder)
#### `ExamStructuresPage.tsx` — Wired to Real API
**Before:** Hardcoded static list, no API calls, non-functional Create/Delete.
**After:** Full CRUD with React Query:
- Lists structures from `GET /api/exam-structures`
- Create dialog with name, industry, module selection → `POST /api/exam-structures`
- Delete button per structure → `DELETE /api/exam-structures/:id`
- Entity filter, search bar
#### `generation.service.ts` — Expanded API Surface
Added 6 new methods:
| Method | Endpoint | Purpose |
|--------|----------|---------|
| `generatePassage()` | `POST /api/exam/reading/generate` | AI passage generation |
| `generateExercises()` | `POST /api/exam/{module}/generate` | AI exercise generation |
| `generateWritingInstructions()` | `POST /api/exam/writing/generate` | AI writing task instructions |
| `generateSpeakingScript()` | `POST /api/exam/speaking/generate` | AI speaking exam script |
| `generateListeningContext()` | `POST /api/exam/listening/generate` | AI listening dialogue/monologue |
| `submitExam()` | `POST /api/exam/generation/submit` | Create exam from generation data |
#### `media.service.ts` — Fixed & Enhanced
- Fixed avatar video endpoint (was pointing to TTS, now correctly uses `/exam/avatar/video`)
- Added `createAvatarVideo()`, `getVideoStatus()`, `generateSpeakingAudio()`
- Proper TypeScript `Avatar` interface
### 2.3 Backend Changes
#### `ai_controller.py` — 7 New Generation Modes
Enhanced the `POST /api/exam/{module}/generate` endpoint with dispatch logic:
| Flag | Handler | AI Prompt |
|------|---------|-----------|
| `generate_passage` | `_generate_passage()` | Generates reading passage at CEFR level |
| `generate_instructions` | `_generate_writing_instructions()` | Generates writing task instructions |
| `generate_script` | `_generate_speaking_script()` | Generates speaking exam script |
| `generate_context` | `_generate_listening_context()` | Generates listening dialogue/monologue |
| `generate_exercises` | `_generate_exercises()` | Generates exercises from passage text |
| (default) | Generic questions | Generates N questions for module |
New endpoint: `POST /api/exam/generation/submit`
- Creates `encoach.exam.template` record
- Creates `encoach.exam.custom` record with sections per module
- Supports approval/skip-approval workflow
Fixed `exam_generate_save`:
- Proper model access via `request.env["model"]` instead of `.get()`
- Question type and difficulty validation against valid field values
#### New Model: `encoach.exam.structure`
**File:** `backend/custom_addons/encoach_exam_template/models/exam_structure.py`
- Fields: name, entity_id, industry, modules (JSON), config (JSON), active
#### New Controller: `exam_structures.py`
**File:** `backend/custom_addons/encoach_exam_template/controllers/exam_structures.py`
| Route | Method | Purpose |
|-------|--------|---------|
| `/api/exam-structures` | GET | List structures with pagination & entity filter |
| `/api/exam-structures` | POST | Create new structure |
| `/api/exam-structures/:id` | DELETE | Delete structure |
#### Security
- Added `access_encoach_exam_structure_user` to `ir.model.access.csv`
---
## 3. Test Results
### 3.1 API Tests (12/12 passed)
| # | Test | Status | Result |
|---|------|--------|--------|
| 1 | Reading Passage Generation | **PASS** | 1,819 chars generated about marine life |
| 2 | Exercise Generation (MCQ, Fill, T/F) | **PASS** | 3 exercises with correct answers |
| 3 | Listening Context Generation | **PASS** | 1,710 chars campus tour dialogue |
| 4 | Writing Instruction Generation | **PASS** | 550 chars letter writing task |
| 5 | Speaking Script Generation | **PASS** | 1,116 chars examiner script |
| 6 | Standard Question Generation (5 Q's) | **PASS** | 5 diverse question types at C1 |
| 7 | Listening Audio TTS (ElevenLabs) | **PASS** | 95KB audio/mpeg generated |
| 8 | Save Generated Questions to DB | **PASS** | 3 questions persisted |
| 9 | Exam Submission (for approval) | **PASS** | Exam #6, status: draft |
| 10 | Exam Submission (skip approval) | **PASS** | Exam #7, status: published |
| 11 | Exam Structure Create | **PASS** | Structure #1 with 4 modules |
| 12 | Exam Structure List | **PASS** | 1 structure returned |
### 3.2 Browser Tests (all modules verified)
| Module | AI Feature | Verified |
|--------|-----------|----------|
| Reading | Passage generation | Yes — full passage displayed in textarea |
| Reading | Exercise type selection (5 types) | Yes — checkboxes functional |
| Listening | Context generation | Yes — dialogue text generated |
| Listening | Audio TTS | Yes — audio generated via ElevenLabs |
| Writing | Instruction generation | Yes — letter task with 4 points |
| Speaking | Script generation | Yes — examiner questions generated |
| Speaking | Avatar selection (7 avatars) | Yes — dropdown populated |
| Submission | "Submit for approval" | Yes — toast "Exam submitted" |
| Structures | Page loads with API data | Yes — shows created structure |
---
## 4. Files Changed
### Backend (5 new, 4 modified)
```
NEW backend/custom_addons/encoach_exam_template/models/exam_structure.py
NEW backend/custom_addons/encoach_exam_template/controllers/exam_structures.py
MOD backend/custom_addons/encoach_exam_template/models/__init__.py
MOD backend/custom_addons/encoach_exam_template/controllers/__init__.py
MOD backend/custom_addons/encoach_exam_template/security/ir.model.access.csv
MOD backend/custom_addons/encoach_ai/controllers/ai_controller.py (major)
```
### Frontend (4 modified)
```
MOD frontend/src/pages/GenerationPage.tsx (complete rebuild, 900+ lines)
MOD frontend/src/pages/ExamStructuresPage.tsx (API wiring)
MOD frontend/src/services/generation.service.ts (6 new methods)
MOD frontend/src/services/media.service.ts (fixed endpoints)
```
---
## 5. Known Limitations / Next Steps
1. **Level & Industry modules** — UI renders but no specific generation logic (needs spec)
2. **Upload Exam** — "Upload" card/buttons are placeholders (file upload not yet wired)
3. **Preview module** — Button disabled (needs exam preview component)
4. **Rubric/Grading** — Dropdowns render but not yet populated from API
5. **Exam Structure in Generation** — Dropdown has static options; could be wired to `/api/exam-structures` for dynamic loading
6. **Avatar Video Generation** — Backend endpoint exists, frontend wired, but needs ELAI API key to test live
---
## 6. How to Test
```bash
# Backend
cd /Users/yamenahmad/projects2026/odoo/odoo19
micromamba run -n odoo19 python3 odoo/odoo-bin -c odoo.conf -d encoach_v2 -u encoach_exam_template --stop-after-init
micromamba run -n odoo19 python3 odoo/odoo-bin -c odoo.conf -d encoach_v2
# Frontend
cd frontend && npm run dev
# Visit http://localhost:8080/admin/generation
```
---
*Report generated on April 11, 2026*

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