Cache Statistics for Offline Viewing
The statistics dashboard must cache the most recently loaded statistics data locally on the device so that the dashboard remains accessible when the user is offline. The cache should store the complete dataset including chart data and summary card values. When online, the cache should be refreshed automatically on dashboard load and invalidated when new activities are registered. A visible indicator should communicate when cached data is being displayed. The cache implementation uses the stats-cache-manager component backed by local device storage.
User Story
Audience Summaries
Offline statistics caching directly addresses the operational reality of peer mentors working across Norway's diverse geography, including rural and northern regions with unreliable connectivity. When a peer mentor sits down with a coordinator or presents their contributions at a community event, a blank statistics screen undermines their credibility and motivation. Caching ensures that the value the platform delivers is always accessible, protecting user trust and reducing churn. This feature also supports the broader organizational mission by ensuring that volunteer engagement data remains visible and actionable regardless of network conditions — a key differentiator for field-facing social sector applications.
This story depends on the core statistics dashboard (story-activity-statistics-dashboard-peer-mentor-001) and introduces cross-cutting infrastructure via the stats-cache-manager component. Delivery involves coordination between the data layer, UI, and connectivity detection logic. Five acceptance criteria must be validated across online, offline, and reconnection states — requiring device-level testing on both iOS and Android in airplane mode. The automatic cache refresh on reconnection and invalidation on new activity registration add complexity that should be scoped carefully to avoid race conditions.
Plan for integration testing with the activity registration flow and allocate time for edge case handling around empty cache states and sync conflicts.
Implement the stats-cache-manager component backed by local device storage (e.g., shared_preferences or hive) to persist the full statistics dataset including chart data and summary card values. On dashboard load while online, fetch from the server and write to cache atomically. On offline load, read from cache and display a visible offline indicator banner. Subscribe to connectivity change events to trigger automatic refresh when the device reconnects — debounce this to avoid redundant fetches.
Hook into the activity registration flow to invalidate the cache on successful new activity submission. Handle the empty-cache-offline state with a dedicated empty state widget. Ensure cache reads and writes are async and non-blocking to keep the UI responsive. Write unit tests for cache invalidation logic and integration tests for the offline/online transition flow.
Acceptance Criteria
- Given I have previously loaded my statistics while online, When I open the statistics screen while offline, Then I see my most recently cached statistics with a banner or indicator informing me that I am viewing offline data
- Given I am online and load the statistics dashboard, When the data loads successfully, Then the local cache is updated with the new data for future offline use
- Given I register a new activity while offline, When I later sync and reload the statistics, Then the cache is invalidated and updated to include the newly registered activity
- Given the cache is empty and I am offline, When I open the statistics screen, Then I see an informative empty state explaining that statistics are unavailable offline and prompting me to connect to load data
- Given cached data is displayed, When I regain connectivity, Then the dashboard automatically refreshes from the server without requiring manual intervention
Business Value
Peer mentors frequently operate in community settings, homes, and remote locations where connectivity is unreliable. All three organizations serve users across Norway including rural and northern regions. Offline capability prevents the frustration of a blank statistics screen and ensures peer mentors can access their data during meetings or presentations where demonstrating their contribution is valuable.
Components
- Statistics Cache Manager data
- Stats Cache Invalidator infrastructure
- Stats Repository data
- Supabase Stats Database Views infrastructure
- Coordinator Statistics BLoC infrastructure
- Personal Statistics BLoC infrastructure