1. At a glance
Sabiyyah is a Year 1 student (grade 239 ALIMGY1) at HidayatUnNisa (institution 12). The example teaches one subject — Arabic (subject 102) — through 2025-2026, evaluates it, releases a report card, validates the year and promotes her to Year 2 (grade 240 ALIMGY2) in 2026-2027.
| What | Value in this run |
|---|---|
| School year | 42 · 2025-2026 · 2025-01-06 → 2025-12-19 · two semesters |
| Class | 34 · ALIMGY1C1 (2025-2026) · grade 239 · homeroom Amina Yusuf |
| Subject offered | 46 · ARABICY1-2025 · 3 lessons a week, 71 in the year |
| Programme | 4 chapters weighted 15 / 25 / 30 / 30 = 100, 12 objectives, 4 reserved chapter tests |
| Tests | 72 Unit Test 1 (80/100) · 73 Vocabulary Quiz (absent) · 74 Reading Test (75/100) · 75 Listening Quiz (draft) |
| Report card | template RC-2025-G1, term “Semester 1 - 2025”, average 77.5, “Competent”, approved then released |
| Promotion | rule mode evaluations, pass 50 → Meets → class 10 ALIMGY2C, grade 240 |
2. How the model fits together
There are five words to hold on to, and they map one-to-one onto screens:
| Word | What it is | Where it is edited |
|---|---|---|
| Programme | One subject of one grade in one school year | Curriculum → Programmes (Chapters) |
| Chapter | An ordered part of the year with a weight; may reserve lessons for its test | same screen |
| Objective | What the class must be able to do; each counts equally inside its chapter | same screen |
| Week plan | Which objectives the class works on in which week | Teaching → Week plan |
| Lesson log | What was actually taught in one lesson, objective by objective | Teaching → Lesson log |
App\Support\ProgrammeProgress), so the teacher’s screen, the administrator’s screen and the family’s screen can never disagree.3. Administrator: set the year up
Admin Do these in order. Each one is what the next needs.
PRG-ALIMGY1-42 “ALIMGY1 programmes 2025-2026” without anyone touching a template. The national catalogue (one document per grade and school year, shared by every university) lives at Settings → Curriculum catalogue (national) and is super-admin only. Step 1 of Curriculum Onboarding now shows your programmes instead.1 Create the school year and its semesters
Path: Settings → Academic periods · /settings
Do: add 2025-2026 (start 2025-01-06, end 2025-12-19, not current — 2026-2027 stays current), then two terms on the school: “Semester 1 - 2025” and “Semester 2 - 2025”.
Why: the week plan takes its weeks from the terms; without them there are no weeks to place objectives in.
- Period is visible in every “School year” picker.
- Both terms appear under the school’s calendar.
2 Offer the grade and create the class
Path: Multi-university → Grades, then Students → Classes · /classes
Do: make sure grade 239 (ALIMGY1) is offered for 2025-2026, then create the class ALIMGY1C1 (2025-2026) in that year with grade 239 and a homeroom teacher.
- The class shows the right school year and grade.
- The homeroom teacher can open the class (this is what lets a teacher plan and mark for it).
3 Add the subject to the class, with lessons per week
Path: Curriculum setup → Institution subjects, then Class subjects
Do: offer Arabic for grade 239 in 2025-2026, then link it to the class with 3 lessons per week.
Why: the programme’s capacity check is “lessons per week × teaching weeks”, and the week plan can only count lessons for a subject the class actually has.
- The class-subject row shows 3 periods a week.
- The timetable builder lists the class and the subject in its drawer.
4 Build the timetable (real lesson slots)
Path: Timetable builder
Do: put Arabic in the same three weekly slots the subject has in the live year, publish the timetable.
Why: the year’s 71 lessons are counted from the published timetable, minus term gaps and holidays. Without slots the programme editor warns that lessons cannot be counted.
- The guided trace at the bottom of the builder turns green for Timetable.
- Coverage shows subjects timetabled, not a 0% figure.
5 Build the programme: chapters, weights, objectives
Path: Curriculum setup → Programmes (Chapters) → Open the programme editor · /curriculum/programmes
Do: open the programme for Arabic · grade 239 · 2025-2026 and add four chapters. Give each a weight and list its objectives with an estimated number of lessons. Reserve one test lesson at the end of each chapter.
| Ch. | Title | Weight | Objectives | Est. lessons |
|---|---|---|---|---|
| 1 | Greetings and introductions | 15 | Holds a short conversation · greets and introduces themselves · asks and answers simple questions | 7 |
| 2 | The Arabic alphabet and sounds | 25 | Names all the letters · writes joined forms · reads vowelled words | 10 |
| 3 | Everyday vocabulary | 30 | Family and classroom objects · numbers 1–20 · daily routine | 10 |
| 4 | Reading short texts | 30 | Reads aloud · answers questions · summarises | 11 |
- The programme list shows
4 chapters · 12 objectives · 100 / 100. - The budget card reads “71 lessons, planned 38” — the plan fits the year.
- Deleting an objective that is already planned or taught is refused (
OBJECTIVE_IN_USE).
6 Tell the promotion rules how the year is decided
Path: Promotion rules
Do: choose Arabic · 2025-2026 · grade 239, set the mode to All published marks (evaluations & graded homework), pass mark 50, no failed subjects allowed, and leave “every term must have a mark” off.
7 Create the report card template for the year
Path: Report cards
Do: add a template for grade 239 in 2025-2026 (here RC-2025-G1, copied from the 2026 card so the layout matches).
4. Teacher: plan, teach, test
Teacher Amina Yusuf teaches Arabic to this class.
1 Plan the weeks
Path: Teaching → Week plan
Do: pick the class + subject, then drag objectives into weeks (or select a week and press +). Each objective carries a number of lessons; the four chapter tests already appear as reserved rows, so they only need placing.
- Weeks show the lessons that week really has (3 a week here) — an overloaded week is a warning, never a block.
- Placing an objective twice, or after its chapter’s test week, is refused.
2 Log each lesson
Path: Teaching → Lesson log
Do: open today’s lesson. For each objective the lesson touched, choose Done (100%) or Partly and type a percentage; the box starts at “where the class is + 25”, so a class already at 80% is offered 99%, not 50%. If nothing was taught, press Nothing taught and write why — the note is required.
| Lesson date | Objective | After the log |
|---|---|---|
| 2025-01-06 | 1.1 Holds a short conversation | 100% |
| 2025-01-13 | 1.2 Greets and introduces themselves | 100% |
| 2025-01-20 | 1.3 Asks and answers simple questions | 100% |
| 2025-02-03 | 2.2 Writes the letters in their joined forms | 100% |
| 2025-02-10 | 2.3 Reads short vowelled words | 60% |
| 2025-02-17 | 3.1 Names family and classroom objects | 100% |
3 Schedule a test on a real lesson
Path: Assessments (Tests) → Schedule a test
Do: pick a lesson slot, a type and what the test covers. Only chapters the class has started can be ticked — a test cannot examine what was never taught.
4 Enter the scores (draft → published)
Path: Assessments → Scores · /assessment/72/scores
Do: set Out of (here 20), Weight in the result (40), and the chapters it covers; type the marks and publish. Students the class register marked absent are pre-ticked Absent.
| Test | Date | Out of | Weight | Covers | Sabiyyah | State |
|---|---|---|---|---|---|---|
| Arabic Unit Test 1 | 2025-02-24 | 20 | 40 | Ch. 1–2 | 16 → 80/100 | Published |
| Arabic Vocabulary Quiz | 2025-03-06 | 10 | 20 | Ch. 3 | Absent | Published |
| Arabic Reading Test | 2025-03-13 | 20 | 40 | Ch. 2–3 | 15 → 75/100 | Published |
| Arabic Listening Quiz | 2025-03-20 | 10 | 20 | Ch. 3 | — | Draft (not visible to her) |
- Publishing needs a score or Absent for every student (
SCORES_MISSINGnames the ones left blank). - Marks are stored as typed (/20) and copied to the report book as 0–100, which is what report cards, GPA and the student’s results read.
- Once published, changing a mark asks for a reason (≥ 5 characters) and writes an audit line plus a notification to the class and guardians.
5 Homework and assignments use the same gradebook
Path: Homework · Assignment hub
Graded homework writes into the same mark table with its own weight, so it reaches the report card and (if you switch it on in the promotion rule) the year-end decision. Ungraded homework never counts.
5. Student & guardian: what they see
1 Chapter progress
Student /my-progress · Guardian /parent/programs
They see: the class and school year, then each subject with its percentage, how many chapters are completed, the current chapter, and — on demand — the chapter list with a status each. No objective-level teacher notes, and no other class: the API refuses anything outside their own record.
ALIMGY2C · 2026-2027 with four subjects at 0% — the new year has not started. The previous year stays in the record but is not shown as “current”.2 Results, including “Absent”
Student /my-results · Guardian /parent/results
They see: every published test with its mark out of 100 and the average. The vocabulary quiz shows an Absent badge — not “not graded yet” — and the hint says it does not count towards the average. A test still in draft simply does not appear.
3 Report card
/my-report-cards · /parent/bulletins
Only a released card is visible, and once released its marks are frozen for teachers (see below).
6. Year-end validation & promotion
1 Generate, approve and release the report card
Path: Report cards → generate for the class → approve → release
Do: generate for class 34, term “Semester 1 - 2025”, template RC-2025-G1; then move it draft → approved → released.
| Student | Average | Grade | Result | Failed subjects |
|---|---|---|---|---|
| Sabiyyah | 77.5 | Competent | pass | 0 |
77.5 = (80 × 40 + 75 × 40) ÷ (40 + 40). The absent quiz contributes nothing — it is neither a zero nor a missing mark.
REPORT_CARD_RELEASED — the report card of this term has been released, so its scores are locked. An administrator or principal can still correct a mark (with a reason, an audit line and a notification), which is the deliberate escape hatch before the card is regenerated.2 Validate the year
Path: Students → Year-end promotion
Do: pick the school, the year (2025-2026), the source class and the target class; the page lists the students with their combined result and a decision.
| Student | Overall | Failed | Decision | Subject results |
|---|---|---|---|---|
| Sabiyyah | 77.5 | 0 | Meets | ARABICY1 77.5 (pass) |
- Incomplete means a mark is missing (when “every term must have a mark” is on) or there are no marks at all.
- Shortfall means the overall is below the pass mark, or too many subjects failed — the reason is spelled out (“Overall 46 < 50”, “Failed 2 subject(s) (max 0)”).
- The decision is advisory: the administrator still chooses whom to promote.
3 Promote
Same page → select the students → Promote
Do: choose the target class of the next year — ALIMGY2C (grade 240, 2026-2027) — and promote.
What the system does: it creates the new enrolment for the new year, keeps last year’s enrolment as history (with a pointer to the class she moved to), and refuses a student who is already enrolled in that year, a class that is full, or a grade that does not match the class.
| Year | Class | Grade | Status | Points to |
|---|---|---|---|---|
| 2025-2026 | ALIMGY1C1 (2025-2026) | 239 | Enrolled | ALIMGY2C |
| 2026-2027 | ALIMGY2C | 240 | Enrolled (new) | — |
/my-progress returned ALIMGY2C · 2026-2027 and her results still listed the three published tests (80, Absent, 75). The draft test stayed invisible.7. What the model decides
| Question | Decision |
|---|---|
| Must chapter weights total 100? | No. The editor warns and offers “split evenly”; progress is scaled by the total. A total of zero is refused, because progress would be stuck at 0%. |
| Do objectives have weights? | No. Each counts equally inside its chapter; emphasis is expressed by the chapter weight. |
| Free percentage or one step per objective? | Both. “Done” = 100; “Partly” takes any 1–99, pre-filled from where the class is. Progress is the furthest any log reached, so it never slides back. |
| Plan chapters or objectives? | Chapters structure, objectives plan. The week plan holds objectives; the chapter carries the weight and the reserved test. |
| “Per hour / per day”? | A lesson estimate, not a slot binding. Objectives are planned per week against the lessons that week really has. Only tests are bound to a real slot. |
| Same programme, two classes? | Separate. One programme per grade, one plan and one progress figure per class. |
| Score format | The teacher’s own “out of” (default 20), stored as typed, copied to 0–100 on publish; each test has a weight in the subject’s final mark. |
| Absent students | Explicit Absent. No mark row, excluded from averages, must be set before publishing; shown as “Absent” to the family. |
| Editing after publishing | Yes, with a reason, an audit line and a notification — until the report card is released, when teachers are locked out and an administrator must step in. |
| Who sees progress | Student and guardian, chapter level only. Objectives stay with the teacher; marks live on Results. |
8. Evidence: the exact records
Everything below was read back from the database after the run, not copied from a screen.
| Record | Where | Value |
|---|---|---|
| School year | academic_periods | 42 · 2025-2026 |
| Terms | institution_schedule_terms | Semester 1 - 2025, Semester 2 - 2025 |
| Class | institution_classes | 34 · ALIMGY1C1 (2025-2026) |
| Offering / class subject | institution_subjects, institution_class_subjects | 46 · Arabic · 3 lessons/week |
| Timetable | institution_schedule_timetables | 28 · 8 slots · 3 Arabic lessons a week |
| Chapters | curriculum_chapters | 37, 38, 39, 40 · weights 15 / 25 / 30 / 30 |
| Objectives | outcome_criterias | 1129–1140 · 12 rows, each inside a chapter |
| Week plan | class_week_plans | 12 objectives over 12 weeks (2025-01-06 → 2025-03-24) |
| Lesson logs | institution_lesson_coverage | 6 lessons, each a row per objective with a percentage |
| Tests | assessments, assessment_chapters | 72–75 · chapter coverage recorded |
| Marks | assessment_scores → assessment_item_results | 16/20 → 80 · absent · 15/20 → 75 |
| Report card | institution_students_report_cards | average 77.5 · approved · released |
| Promotion rule | institution_promotion_rules | mode evaluations · pass 50 · 0 failed subjects |
| Promotion | institution_class_students | new row for class 10 / grade 240; last year’s row points to it |
9. Known limits & next steps
- Coverage board. It still offers an outcome period filter, an artefact of the old model. The old per-slot objective links were removed (21 rows), so the filter now lists periods but no linked outcomes; the board’s own delivery data comes from the lesson log. Porting that filter to chapters is the last step of retiring the old model, and until then the
outcome_periodstable is kept (17 rows, inert). The retirement itself is scripted and **not applied**:openemis-core/sql/migrations/queued__retire_outcome_periods.sql(it drops the template from the outcome primary key and deletesoutcome_periods; its header lists the four code re-points and says to run it after UAT). - The national catalogue is a separate page.
/curriculum-cataloguelists, adds, renames and deletes the outcome documents per school year. A school does not need it: it exists for the shared national scope and the legacy outcome analysis. The catalogue UI inside Curriculum Onboarding is still reachable with?catalogue=1and will be removed in the same release as the migration above. - One year at a time for families. A promoted student’s progress page shows the current year; the previous year is stored but not selectable yet.
- Two old screens retired, not deleted.
/lesson-planningand/teacher-coverageforward to the new screens and are out of the navigation. Their URLs stay so old bookmarks do not dead-end. - Old records removed: 21 per-slot objective links, 2 legacy outcome marks, 0 lesson-outcome links (already empty) — backed up first to a SQL dump.
- Report card average is computed when the card is generated; regenerating after a mark change is deliberate, and the release lock is what protects the printed document.
.e2e/ (seed-prev-year.sql, seed-prereq.sql, cleanup-old-curriculum.sql, api.ps1) and every request/response is in .e2e/log.jsonl.