Coordinator Statistics Service
Component Detail
Description
Core business logic service that fetches and processes aggregated statistics for a coordinator's peer mentor roster. Applies RLS-aware queries against Supabase pre-aggregated views, enforces 15-minute cache, and transforms raw rows into dashboard-ready view models.
coordinator-stats-service
Summaries
The Coordinator Statistics Service is the analytics engine that powers every dashboard and reporting surface in the platform. By pre-aggregating coordinator and org-wide performance data from Supabase and enforcing a 15-minute intelligent cache, it ensures that dashboards load quickly without burdening the database with expensive repeated queries as usage scales. This directly protects infrastructure costs as the user base grows and prevents the performance degradation that drives user abandonment. The service also enforces row-level security boundaries, ensuring that coordinators only see data for their own roster — a critical compliance and trust requirement for any organization managing sensitive program data.
This is the highest-complexity component in the statistics feature set, with three upstream dependencies: stats-repository, stats-cache-manager, and role-access-validator. All three must be delivered and integration-tested before this service can be fully validated. The RLS-aware query logic and dual-scope support (coordinator vs org admin) represent the primary testing complexity — plan dedicated QA cycles for each scope permutation and for cache invalidation edge cases such as a coordinator's roster changing mid-cache window. Performance testing under realistic query loads should be included in the definition of done, as a slow service will degrade every dashboard screen that depends on it.
Cache invalidation strategy must be documented to prevent stale data bugs in production.
CoordinatorStatsService is a high-complexity Dart service class injected via the DI layer. It wraps stats-repository calls with stats-cache-manager using coordinatorId + StatsPeriodFilter as the composite cache key, with a 15-minute TTL enforced via DateTime comparison. getCoordinatorStats and getPeerMentorRosterStats query Supabase pre-aggregated views (not raw tables) — ensure the view definitions account for RLS policies so that the mobile client's authenticated session automatically scopes results. getOrgWideStats accepts an orgId and is gated by role-access-validator to prevent coordinators from invoking org-level queries.
View model construction (CoordinatorStatsSummary, List
Responsibilities
- Fetch aggregated stats from Supabase views by org_id + coordinator_id + month
- Enforce 15-minute result cache to avoid repeated heavy queries
- Build view models for KPI cards, bar chart, and donut chart
- Support coordinator vs org admin scope (org admin sees all coordinators)
Interfaces
getCoordinatorStats(String coordinatorId, StatsPeriodFilter filter) → Future<CoordinatorStatsSummary>
getPeerMentorRosterStats(String coordinatorId, StatsPeriodFilter filter) → Future<List<PeerMentorStatSummary>>
getActivityTypeBreakdown(String coordinatorId, StatsPeriodFilter filter) → Future<List<ActivityTypeBreakdown>>
getMonthlyActivitySeries(String coordinatorId, DateRange period) → Future<List<MonthlyStatPoint>>
getOrgWideStats(String orgId, StatsPeriodFilter filter) → Future<OrgWideStatsSummary>
invalidateCache(String coordinatorId)
Relationships
Dependencies (3)
Components this component depends on
Related Data Entities (1)
Data entities managed by this component