Skip to content

UC-ADM-106: Wellness Score Aggregation

1. Metadata

Property Value
ID UC-ADM-106
Actor System (automated) / School Administrator
Trigger Daily batch job (midnight) or manual admin refresh
Pre-conditions At least one student has a completed screening and one logged activity
Post-conditions Wellness Score is updated at student, school, and district level
Priority P1

2. Description

The Wellness Score is the platform's headline KPI — visible on the Admin Dashboard as the primary indicator of program health. It aggregates BMI percentiles, module completion rates, and daily activity logs into a single composite score (0–10) at school and district level.

3. Score Components

Component Weight Data Source
Screening Compliance 30% % of enrolled students with a current screening (< 30 days old)
Module Completion Rate 40% % of assigned modules completed across the school
Daily Activity Rate 30% % of students with at least one logged activity in the last 7 days

Formula: 

Wellness Score (0-10) = 
  (Screening Compliance × 0.3 + 
   Module Completion Rate × 0.4 + 
   Daily Activity Rate × 0.3) × 10

4. Score Display

Level Range Visual
Excellent 8.5 – 10.0 Green
Good 6.5 – 8.4 Blue
Needs Attention 4.0 – 6.4 Amber
At Risk 0 – 3.9 Red

5. Success Scenario

  1. Nightly batch job runs at midnight — aggregates all input data per school.
  2. Score is computed per school and rolled up to district level.
  3. Admin opens the Dashboard — sees the school-level Wellness Score card (e.g., "9.1 / 10").
  4. Admin drills into the score — breakdown shows individual component percentages.
  5. Admin exports the score report for a donor presentation.

6. Acceptance Criteria

  • [ ] Score must refresh at least once every 24 hours automatically.
  • [ ] Manual refresh must be available for admins (with a 15-minute cooldown).
  • [ ] Score must be displayed to one decimal place.
  • [ ] Component breakdown must be visible when the admin hovers or taps the score card.
  • [ ] Historical score trend (last 90 days) must be available as a line chart.

7. Aggregation Flow

graph TD A[Nightly Batch Job] --> B[Fetch all schools] B --> C[For each school: compute 3 components] C --> D[Screening Compliance %] C --> E[Module Completion Rate %] C --> F[Daily Activity Rate %] D --> G[Apply weights and sum] E --> G F --> G G --> H[Store Wellness Score per school] H --> I[Roll up to district average] I --> J[Update Admin Dashboard]