root
22 KiB
Strong Grading System Plan
Purpose
This document defines a stronger grading-system plan for the Alrahma Sunday School API. It is intentionally a planning document, not an implementation patch.
The goal is to move the grading system from a functional calculator into a fair, explainable, auditable, backward-compatible, and policy-driven gradebook.
The current system already has a useful foundation: a centralized semester score service, separated score-entry flows, grading locks, and missing-score override tracking. However, the current scoring model still allows too much ambiguity around blank scores, missing work, validation, and finalization.
The strongest first move is not to redesign every formula. The strongest first move is to kill ambiguity while keeping old data readable and old calculations explainable.
Core Principles
A strong grading system must be:
-
Fair
Missing work must not accidentally improve a student's grade. -
Explainable
Every final score must be traceable to category scores, weights, attendance, exam score, and policy rules. -
Auditable
Locked or finalized scores must preserve the exact inputs and formula used at the time. -
Policy-driven
Grading policy should live in services, configuration, and grading profiles, not scattered controller logic. -
Safe
Invalid scores must be rejected before they reach averages or semester calculations. -
Backward-compatible
Old data must remain readable, displayable, and explainable under the legacy policy that created it. -
Additive, not destructive
The new grading system must be introduced beside the old one first. Existing historical scores must not be silently recalculated, reclassified, hidden, or overwritten.
Non-Negotiable Backward Compatibility Requirement
The system must preserve old data display.
Historical grades must remain visible exactly as they were calculated under the legacy system. The new strong grading system must not reinterpret old blanks, old averages, or old semester scores as if they were created under the new policy.
This is the hard rule:
Old data must remain readable, displayable, and explainable exactly as it was calculated under the legacy system.
The new system must support two modes:
| Mode | Purpose | Formula Source | Data Behavior |
|---|---|---|---|
| Legacy display mode | Show old/historical grades | Existing stored semester values and legacy formula | Do not reinterpret blanks or statuses |
| Strong scoring mode | Calculate future grades under stronger rules | New scoring service/profile | Uses statuses, max points, snapshots, and finalization validation |
Legacy records must show stored values from the existing semester_scores table, such as:
homework_avg
quiz_avg
project_avg
participation_score
attendance_score
ptap_score
midterm_exam_score
final_exam_score
semester_score
Legacy displays should include a visible label:
Legacy Calculation
And a short explanation:
This score was calculated under the legacy grading policy. Blank scores were ignored in category averages, PTAP used legacy dynamic weighting, attendance included one-absence grace, and the semester exam used the legacy 60% weighting.
This is not optional. Without this, the system risks showing old data through new rules and creating disputes that nobody can cleanly answer. Software should not gaslight the gradebook. Humans already do enough of that.
Historical Data Protection Rules
Historical grades must not be automatically recalculated under the new scoring policy.
Rules:
- Existing
semester_scoresrows stay in place. - Existing historical rows are marked as legacy.
- Legacy rows are displayed from stored aggregate values.
- Legacy rows are not forced into the new status model.
- Legacy blanks are not automatically converted to
missing. - Legacy scores are not recalculated unless an authorized admin explicitly starts a recalculation job.
- If recalculation is ever allowed, the original legacy score must be preserved beside the new-policy result.
Recommended display if a historical record is later recalculated for comparison:
legacy_semester_score: 91.4
new_policy_semester_score: 87.2
displayed_score: 91.4 unless admin explicitly chooses otherwise
The default behavior must protect the original displayed score.
Recommended Compatibility Metadata
Do not replace the existing semester_scores table. Keep it.
Add nullable metadata columns:
calculation_mode
calculation_policy_version
snapshot_id nullable
Suggested values:
calculation_mode = legacy | strong
calculation_policy_version = legacy_v1 | strong_v1
Backfill existing rows as:
calculation_mode = legacy
calculation_policy_version = legacy_v1
snapshot_id = null
New strong-system finalized rows should be saved with:
calculation_mode = strong
calculation_policy_version = strong_v1
snapshot_id = related semester_score_snapshots row
This keeps old grade display stable while allowing new scores to become audit-proof.
Display Resolver Requirement
Create a display resolver instead of forcing every grade display through the new scoring engine.
Recommended service:
App\Services\Grading\GradeCalculationDisplayResolver
Responsibilities:
If calculation_mode is legacy:
Load and display existing semester_scores fields.
Show Legacy Calculation badge.
Do not apply new status or profile rules.
If calculation_mode is strong:
Load snapshot and/or strong calculation breakdown.
Show Strong Calculation badge.
Display status-aware category breakdown.
The display layer must not recalculate legacy scores just to show them. It should show the stored values. Recalculating old scores on display is a terrible idea, and yet somehow tempting to developers who enjoy turning page loads into historical revisionism.
Important Policy Clarification: Attendance Grace
The attendance grace rule is school policy.
The current formula effectively gives students one absence before attendance points are reduced:
attendance_score = ((total_days + 1 - absences) / total_days) * 100
This is policy-compliant, but the formula hides the intent. It should be rewritten more explicitly:
grace_absences = 1
effective_absences = max(0, absences - grace_absences)
attendance_score = ((total_days - effective_absences) / total_days) * 100
This keeps the same policy while making the rule clear. Future developers should not have to decode a +1 and wonder whether it is a bug wearing a tiny policy hat.
Phase 0: Lock the Grading Policy Before Writing Code
Before implementation, these policy decisions must be explicit.
| Question | Recommended Decision |
|---|---|
| Are old/historical grades still displayed? | Yes. Always. |
| Are old/historical grades recalculated automatically? | No. Never silently. |
| Are old blanks converted to missing? | No. Old blanks remain legacy behavior unless explicitly migrated by admin workflow. |
| Are scores always out of 100? | No. Add max_points, then normalize to percentages for strong scoring. |
| What does a blank score mean in the new system? | Nothing final. It means pending or unresolved. |
| Does missing work count as zero in the new system? | Yes, unless explicitly excused. |
| Does excused work affect the average? | No. Excused work is excluded from the denominator. |
| Can a class be locked with pending scores in the new system? | No. |
| Can a class be locked with missing work in the new system? | Yes, but missing work counts as zero unless excused. |
| Does attendance have one absence grace? | Yes. This is school policy. |
| Should final scores keep an audit trail? | Yes. Store a calculation snapshot when locking/finalizing new strong scores. |
These decisions are non-negotiable if the system needs to be defensible.
Phase 1: Stabilize the Current Legacy System
Do not start with grading profiles. That is architecture candy. It looks mature, but it does not fix the most dangerous problem first.
The first goal is to stop bad data, protect current behavior with tests, and keep legacy grade display working.
1. Add Tests for Existing Legacy Formulas
Before changing calculation behavior, freeze the current formulas in tests.
Test coverage should include:
homework average ignores blanks
quiz average ignores blanks
project average ignores blanks
participation missing returns null
PTAP with no quiz/project
PTAP with quiz only
PTAP with project only
PTAP with all categories
Fall semester formula
Spring semester formula
attendance with 0 absences = 100
attendance with 1 absence = 100
attendance with 2 absences = reduced score
legacy semester_scores display from stored values
legacy rows are not recalculated on display
This creates a safety net. Without it, every refactor becomes a guessing game with grades, which is exactly as bad as it sounds.
2. Add Central Score Validation
Create one central validator used by every score write path.
Validation rules:
score may be null
score must be numeric when present
score must be >= 0
score must be <= max_points
max_points must be > 0
For the first pass, use max_points = 100 by default.
Example service shape:
final class ScoreValueValidator
{
public function normalizeOrFail(mixed $value, float $maxPoints = 100.0): ?float
{
if ($value === null || (is_string($value) && trim($value) === '')) {
return null;
}
if (!is_numeric($value)) {
throw new InvalidArgumentException('Score must be numeric.');
}
$score = (float) $value;
if ($score < 0 || $score > $maxPoints) {
throw new InvalidArgumentException("Score must be between 0 and {$maxPoints}.");
}
return $score;
}
}
Use this validator in all score-entry paths:
HomeworkScoreService
QuizScoreService
ProjectScoreService
ParticipationScoreService
ExamScoreService
GradingScoreService
This should reject impossible new values without changing how existing historical rows are displayed.
3. Make Attendance Grace Explicit
Refactor the attendance calculation without changing its result.
Replace hidden arithmetic:
(total_days + 1 - absences) / total_days
With named policy logic:
grace_absences = 1
effective_absences = max(0, absences - grace_absences)
attendance_score = ((total_days - effective_absences) / total_days) * 100
Add tests:
| Total Days | Absences | Expected Attendance Score |
|---|---|---|
| 10 | 0 | 100 |
| 10 | 1 | 100 |
| 10 | 2 | 90 |
| 10 | 10 | 10 |
| 10 | 11+ | 0 |
4. Add Legacy Display Badge
Before introducing strong scoring, make the UI able to label old records.
For legacy rows, show:
Policy: Legacy Calculation
Example display:
Semester Score: 91.4
Policy: Legacy Calculation
Attendance: 100.0
PTAP: 88.5
Midterm: 92.0
Note: This score was calculated under the legacy policy. Blank scores were ignored in averages.
This prevents users from assuming legacy and strong scores use the same rules.
Phase 2: Make Missing Scores Explicit for New/Strong Scoring
This phase applies to the new strong scoring path. It must not automatically rewrite old historical records.
Right now, a blank score can mean too many things:
not graded yet
student missing work
student excused
teacher forgot
assignment not applicable
A grading system cannot be fair if the data refuses to say what it means.
1. Add Score Statuses
Every new strong score-bearing record should have both a numeric score and a status.
Minimum statuses:
| Status | Meaning | Counts in Average? | Blocks Finalization? |
|---|---|---|---|
pending |
Teacher has not resolved the item | No | Yes |
scored |
Valid numeric score exists | Yes | No |
missing |
Student did not submit | Yes, as 0 | No |
excused |
Approved exclusion | No | No |
not_assigned |
Does not apply | No | No |
Recommended columns for homework, quiz, project, participation, midterm, and final tables:
status
max_points
excused_reason
locked_at
locked_by
2. Migrate Existing Data Carefully
Do not blindly turn old blanks into missing work. That would punish students for old system ambiguity.
Initial migration mapping for active, not-yet-finalized records:
| Existing Data | Initial Status |
|---|---|
| Numeric score exists | scored |
| Blank/null score | pending |
| Missing override exists and is allowed | excused or not_assigned, depending policy meaning |
For historical finalized legacy records, do not require full status migration just to display them. Keep them as legacy display records.
After migration, teachers/admins must resolve pending items before final lock for strong-scoring sections.
Phase 3: Change Calculation Semantics for Strong Scoring
Once statuses exist, strong category calculations should stop relying on blank/null behavior.
New score handling:
| Status | Calculation Behavior |
|---|---|
scored |
Include normalized score |
missing |
Include 0 |
excused |
Exclude from denominator |
not_assigned |
Exclude from denominator |
pending |
Block finalization |
Normalize every scored item:
normalized_score = (raw_score / max_points) * 100
Then calculate the category average:
category_average = average(all included normalized scores)
This prevents missing work from silently improving a student's grade.
Legacy records must still display legacy stored values. Do not apply this status-aware calculation to historical rows unless an admin explicitly opts into a recalculation workflow.
Phase 4: Add Finalization Validation
Locking a strong-scoring class should not simply flip a flag. It should prove the gradebook is complete enough to finalize.
Create a validator service:
App\Services\Grading\GradebookFinalizationValidator
It should validate:
No pending required scores
All numeric scores are within range
Required categories are present
Required exam score exists
Required participation score exists
Attendance can be calculated
Missing items are either counted as zero or excused
Every student has a calculable final score
If validation fails, return a structured report:
student
category
item
problem
required_action
Example:
Student: Ahmed Ali
Category: Homework
Item: Homework #4
Problem: Pending score
Required action: Mark as scored, missing, excused, or not assigned before locking.
The lock button should become a gate, not a decorative suggestion.
Legacy historical records do not need to pass the new finalization validator just to be displayed.
Phase 5: Add Calculation Snapshots for Strong Scores
When strong grades are finalized or locked, store exactly how the final score was produced.
Create table:
semester_score_snapshots
Recommended fields:
id
student_id
class_section_id
semester
school_year
grading_policy_version
input_json
calculation_json
semester_score
calculated_by
calculated_at
The snapshot should include:
raw scores used
score statuses used
max points used
normalized scores
category averages
category weights
attendance grace policy
exam score
final formula
final score
This protects the school when someone disputes a grade later.
The current semester_scores table can show the latest aggregate. The snapshot proves what was true at finalization.
Legacy historical grades may have no snapshot. That is acceptable as long as they are clearly labeled legacy_v1 and displayed from stored values.
Phase 6: Replace Hardcoded PTAP With Grading Profiles
Only after validation, statuses, legacy display protection, and snapshots are in place should hardcoded weighting be replaced.
Current PTAP behavior changes based on data availability:
No tests and no projects
Tests but no projects
Projects but no tests
All categories exist
That is flexible, but dangerous. It lets missing or unentered data affect the formula.
Recommended Tables
grading_profiles
Fields:
id
name
school_year
semester
class_section_id nullable
is_default
version
created_by
created_at
updated_at
grading_profile_categories
Fields:
id
grading_profile_id
category_key
weight
required
redistribute_if_missing
Example Profile
| Category | Weight | Required | Redistribute If Unused |
|---|---|---|---|
| homework | 15 | Yes | No |
| quiz | 15 | Configurable | Yes |
| project | 15 | Configurable | Yes |
| participation | 15 | Yes | No |
| attendance | 10 | Yes | No |
| exam | 30 | Yes | No |
Important distinction:
Category not used by profile -> redistribute its weight
Category assigned but scores pending -> block lock
Category assigned but student missing -> count as zero
Category excused -> exclude according to policy
Do not redistribute weight just because a teacher forgot to enter grades. That would be grading by accident, which is somehow worse than grading by spreadsheet.
Legacy rows continue using legacy PTAP display and must not be forced into grading profiles.
Phase 7: Opt-In Activation Strategy
Strong scoring should be activated by class section, semester, and school year. It should not globally replace legacy behavior in one switch.
Recommended activation metadata:
class_section_id
school_year
semester
calculation_mode = legacy | strong
grading_profile_id nullable
activated_by
activated_at
Activation rules:
- Existing historical records remain
legacy. - Current active sections may remain
legacyuntil admins choose migration. - New future sections can default to
strongonce the system is ready. - A class section using
legacymust continue calculating and displaying using the legacy service. - A class section using
strongmust use statuses, max points, finalization validation, and snapshots. - Switching a section from legacy to strong should require an admin confirmation and a preflight report.
Preflight report should show:
number of numeric scores that will become scored
number of blanks that will become pending
number of overrides requiring review
students blocked from finalization until pending items are resolved
No quiet migrations. Quiet migrations are where data integrity goes to disappear.
Phase 8: Refactor Controllers Last
Controllers should not contain grading policy.
Final desired flow:
Controller receives request
Request validates input shape
Application service saves score/status
Scoring mode resolver selects legacy or strong path
Scoring service recalculates draft score
Finalization validator blocks or allows lock for strong mode
Snapshot service records locked strong calculation
Display resolver shows legacy or strong breakdown
Controllers should not know formulas. They should not decide whether missing counts. They should not know category redistribution rules.
Controllers are traffic cops, not education philosophers.
Recommended Implementation Order
| Step | Work | Risk Reduced |
|---|---|---|
| 1 | Add tests for current legacy formulas and legacy display | Prevent accidental formula/display drift |
| 2 | Add compatibility metadata to semester_scores |
Preserve old records clearly |
| 3 | Add legacy/strong display resolver | Keep old data visible |
| 4 | Add central score validation | Stop impossible new scores |
| 5 | Make attendance grace explicit | Preserve policy and improve clarity |
| 6 | Add max_points columns |
Enable normalization |
| 7 | Add status columns |
Remove blank-score ambiguity for strong scoring |
| 8 | Build category calculator using statuses | Fix missing-score fairness |
| 9 | Add finalization validator | Stop invalid strong locks |
| 10 | Add calculation snapshots | Audit-proof locked strong grades |
| 11 | Add grading profiles | Remove hardcoded weights for strong mode |
| 12 | Add opt-in activation by class/semester | Prevent disruptive rollout |
| 13 | Refactor controllers | Clean architecture after behavior is safe |
MVP Strong Upgrade
The smallest serious upgrade is:
1. Keep current legacy formulas.
2. Keep old data display from stored semester_scores values.
3. Add calculation_mode and calculation_policy_version metadata.
4. Add legacy display badge.
5. Add central score validation for new writes.
6. Make attendance grace explicit without changing results.
7. Add score statuses for active/future strong-scoring sections.
8. Treat missing as zero, excused as excluded, and pending as blocking lock in strong mode only.
9. Add a lock validation report for strong mode.
10. Add calculation snapshots on strong-mode lock.
This improves fairness and auditability without breaking old records or immediately changing all weights.
After that, replace PTAP branching with grading profiles.
Hard Safety Rules
- Do not change formulas and database semantics in the same step without tests.
- Do not silently recalculate historical scores.
- Do not convert old blanks to missing for historical records.
- Do not hide legacy data because it lacks new statuses.
- Do not activate strong scoring globally without class/semester-level opt-in.
- Do not display a strong-policy explanation for a legacy-policy score.
- Do not let a lock action become the first time the system discovers incomplete data.
That is how a school ends up unable to explain whether grades changed because of policy, migration, code, or a null-handling goblin hiding in the service layer.
Final Recommendation
Do not begin by building grading profiles.
Begin by making legacy display safe and every new score state explicit.
The strongest first milestone is:
Old grades remain visible under Legacy Calculation, and future strong-mode grades cannot be locked until every score is classified as scored, missing, excused, pending, or not assigned.
Once that is true, the grading system becomes defensible. Until that is true, every formula is built on fog.