Stats Data Models
Component Detail
Description
Typed Dart data classes representing the stats domain: StatsSnapshot (totals for a given scope and time window), PeerMentorStatRow (one row in coordinator's breakdown list), ChartDataPoint (x/y pair for fl_chart), and TimeWindow enum. All models are immutable and include copyWith factories.
stats-models
Summaries
The Stats Data Models component establishes the foundational data structures that power all analytics and reporting capabilities within the mobile application. By providing standardized representations of session counts, hours, and reimbursement totals, this component ensures that every stakeholder — from peer mentors reviewing their own activity to coordinators evaluating chapter performance — sees consistent, accurate data. Consistent data models directly reduce the risk of reporting discrepancies, which can erode trust in the platform and increase support overhead. Immutable models with copyWith factories also reduce the likelihood of data corruption bugs reaching end users, protecting the organization's reputation and reducing the cost of post-release defect resolution.
Stats Data Models is a low-complexity foundational component with no external dependencies, making it an ideal early-sprint deliverable that unblocks all downstream stats features. Because it defines shared contracts (StatsSnapshot, PeerMentorStatRow, ChartDataPoint, TimeWindow) used across the stats UI, repository, and service layers, it must be completed and reviewed before any dependent component begins development — a sequencing constraint that should be reflected in the sprint plan. Testing effort is minimal: unit tests covering fromJson deserialization, copyWith correctness, and TimeWindow enum exhaustiveness. Risk is low, but any schema changes after dependent components are built will cascade widely, so stakeholder sign-off on the model structure early is critical.
Stats Data Models defines four immutable Dart types that serve as the canonical data contract for the stats feature domain. StatsSnapshot aggregates session count, hours, and optional reimbursement totals for a given scope and time window, while PeerMentorStatRow holds per-mentor breakdowns for coordinator list views. ChartDataPoint wraps a DateTime and double value for direct consumption by fl_chart widgets. TimeWindow is an enum with month, quarter, and year values used to parameterize repository queries and UI selectors.
All types expose fromJson factories for JSON deserialization from Supabase responses and copyWith for state management patterns (e.g., Riverpod StateNotifier updates). No external dependencies — this layer is purely domain-typed Dart. When the backend view schema changes, update fromJson here first, then propagate downstream.
Responsibilities
- Define StatsSnapshot with session count, hours, and optional reimbursement total
- Define PeerMentorStatRow with peer mentor identity and individual totals
- Define ChartDataPoint for chart rendering
- Define TimeWindow enum with month, quarter, year values
Interfaces
StatsSnapshot.fromJson(Map<String, dynamic> json)
StatsSnapshot.copyWith({...})
PeerMentorStatRow.fromJson(Map<String, dynamic> json)
ChartDataPoint(DateTime date, double value)
TimeWindow.values
TimeWindow.month
TimeWindow.quarter
TimeWindow.year