Gradebooks compute. Component marks roll into unit grades, units into a subject grade, subjects into a progress measure. Each step is simple. The problem is what happens when something upstream changes six months in.
Stored derived values go stale silently
The usual design stores computed grades because recomputing is slow. Then a teacher corrects a mark from February, and the unit grade, the subject grade, the predicted outcome, and the intervention flag are all still showing the old answer.
Nobody finds out. The numbers look plausible. A student stays on an intervention list they should have left in March.
Make the dependency explicit
You need to know what depends on what before you can know what went stale:
grade_derivations
output_kind, output_id
input_kind, input_id
computed_at
formula_versionChanging an input marks every dependent output dirty. A worker recomputes dirty rows and clears the flag. It is a small dependency graph, not a framework, and it turns “which grades are wrong” from unanswerable into a query.
Version the formula, not just the result
Weightings change between academic years, and sometimes mid-year by agreement. A grade computed under last year’s rules must not silently change when the rule changes.
Store formula_version on the derived row. Recomputation applies the version in force at the time the underlying work was assessed — not today’s. Otherwise reprinting a report from last term produces different numbers than the one the parents already have.
Show the working
Every derived grade should be able to explain itself: which components, what weights, what was missing, which rule version. One expandable panel.
Teachers do not trust numbers they cannot reproduce, and a teacher who does not trust the gradebook keeps a spreadsheet. Once that happens the system is documentation of a process happening elsewhere.
Absent is not zero
The most common calculation bug in education software. A missing assessment must not contribute zero to an average — it must be excluded, and the grade marked provisional. Treating absence as zero produces failing grades for students who were ill, and it is the single fastest way to lose a school’s confidence.