Stats Repository
Component Detail
Description
Data access component that queries Supabase materialized views or database views to retrieve pre-aggregated activity statistics. Avoids client-side computation on large datasets by delegating all aggregation to the database layer. Returns typed StatsSnapshot and PeerMentorStatRow models.
stats-repository
Summaries
The Stats Repository is the performance foundation of the entire reporting and dashboard experience. By delegating all aggregation work to pre-computed database views in Supabase rather than processing raw data on users' devices, it ensures that peer mentors and coordinators see their statistics instantly — even as activity records grow into the thousands. Fast, reliable statistics directly support staff engagement and trust in the platform, which in turn reduces administrative overhead and increases adoption. For coordinators managing multiple chapters, the ability to drill down into per-peer-mentor breakdowns without delay translates into faster decision-making and more responsive program management.
This component is foundational infrastructure whose quality directly affects the perceived quality of the entire product.
The Stats Repository is a medium-complexity data component with zero declared external service dependencies, making it one of the more self-contained deliverables in the data layer. However, it has a critical upstream dependency on the database schema: Supabase materialized views or query views must be designed and deployed before this component can be implemented and tested end-to-end.
This creates a dependency chain that must be sequenced carefully — database view design, Stats Repository implementation, and then all dashboard and reporting features that consume it. The invalidateCache() interface implies a caching layer that must be designed for correctness under concurrent access patterns. Testing requires representative datasets covering peer mentor, coordinator, and cross-chapter scenarios with date range edge cases. Plan for integration testing time against a staging Supabase instance.
Stats Repository is a data-layer component that abstracts all Supabase query logic behind a typed async interface, returning StatsSnapshot and PeerMentorStatRow models consumed by dashboard and reporting features. It exposes five methods: getPeerMentorStats() and getCoordinatorStats() return role-scoped StatsSnapshot aggregates for the primary dashboard views; getPeerMentorBreakdown() returns a List
The data models covered span activity, reimbursement, and peer-mentor entities, so view schemas must join across all three. Cache invalidation strategy should be event-driven, triggered after any activity write or approval state change, to avoid stale totals in the dashboard.
Responsibilities
- Query Supabase activity stats views with date range and role filters
- Return peer mentor own totals (sessions, hours, reimbursement)
- Return coordinator aggregated totals scoped to authorized chapters
- Return per-peer-mentor breakdown rows for coordinator drill-down
Interfaces
getPeerMentorStats(String userId, DateTimeRange range) Future<StatsSnapshot>
getCoordinatorStats(List<String> chapterIds, DateTimeRange range) Future<StatsSnapshot>
getPeerMentorBreakdown(List<String> chapterIds, DateTimeRange range) Future<List<PeerMentorStatRow>>
getChartDataPoints(String userId, DateTimeRange range, TimeWindow window) Future<List<ChartDataPoint>>
invalidateCache()
Relationships
Dependents (2)
Components that depend on this component
Related Data Entities (3)
Data entities managed by this component
Used Integrations (1)
External integrations and APIs this component relies on