Coordinator Statistics BLoC
Component Detail
Description
BLoC state management unit for the coordinator statistics dashboard. Handles loading, filtering, refreshing, and error states. Subscribes to activity registration events to trigger cache invalidation and dashboard refresh when new activities are recorded.
stats-bloc
Summaries
The Coordinator Statistics Dashboard component delivers real-time visibility into program performance, enabling coordinators and org administrators to make data-driven decisions without waiting for manual reports. By surfacing activity registrations, participation trends, and period-over-period comparisons instantly, this component reduces administrative overhead and accelerates the feedback loop between program execution and strategic planning. The auto-refresh capability ensures decision-makers always view current data, eliminating costly delays caused by stale dashboards. This directly supports retention, accountability, and program quality — all of which are key competitive differentiators in peer mentoring platforms.
This is a medium-complexity BLoC state management unit with a clearly scoped responsibility set, making it a predictable deliverable within a two-week sprint. Its primary dependency is the coordinator-stats-service, which must be completed and stable before integration testing can begin — plan for a hard dependency gate here. The auto-refresh via activity registration stream introduces an event-bus coupling that requires coordinated testing with the activity registration flow. QA should cover loading, loaded, and error states, plus filter transitions and cache invalidation scenarios.
Risk: event stream subscription leaks if BLoC disposal is not properly tested; include lifecycle tests in the acceptance criteria.
CoordinatorStatsBloc follows Flutter's BLoC pattern, accepting a CoordinatorStatsService via constructor injection for testability. It exposes three event types — LoadCoordinatorStats, ChangeStatsFilter, and RefreshStats — each mapping to distinct async state transitions: CoordinatorStatsLoading → CoordinatorStatsLoaded(CoordinatorStatsSummary) or CoordinatorStatsError. The bloc subscribes to an activity registration stream (likely via a StreamSubscription on a shared event bus or repository stream) to trigger automatic cache invalidation and re-fetch. Implement using bloc 8.x with mapEventToState replaced by on
Dispose subscriptions in close() to prevent memory leaks. StatsPeriodFilter should be an immutable value object for safe equality comparison in filter-change handling.
Responsibilities
- Manage loading / loaded / error states for dashboard data
- React to filter change events and re-fetch stats
- Subscribe to activity registration stream for auto-refresh
- Coordinate coordinator-level and org-admin-level data fetching
Interfaces
CoordinatorStatsBloc(CoordinatorStatsService statsService)
LoadCoordinatorStats(StatsPeriodFilter filter)
ChangeStatsFilter(StatsPeriodFilter filter)
RefreshStats()
CoordinatorStatsLoading
CoordinatorStatsLoaded(CoordinatorStatsSummary summary)
CoordinatorStatsError(String message)