Stats Cache Invalidator
Component Detail
Description
Listens for Supabase realtime events on the activities table and triggers invalidation of the stats Riverpod provider. Ensures the dashboard reflects newly registered activities immediately without requiring manual pull-to-refresh. Connects Supabase realtime channel subscriptions to Riverpod ref.invalidate calls.
stats-cache-invalidator
Summaries
The Stats Cache Invalidator ensures that users always see up-to-date activity statistics on their dashboard the moment a new activity is recorded — no manual refreshing required. This real-time feedback loop directly improves user engagement and trust in the platform, as users immediately see the impact of their actions. By eliminating stale data, the organization reduces support requests related to 'missing' activities and increases user confidence in data accuracy. The automatic, instant update experience is a key competitive differentiator in activity-tracking applications where users expect live feedback.
This component protects the business from churn caused by perceived data reliability issues, delivering measurable ROI through improved retention and reduced support overhead.
The Stats Cache Invalidator is a medium-complexity mobile component with a well-scoped responsibility: bridging Supabase realtime events to Riverpod state invalidation. Development effort is moderate, requiring familiarity with both Supabase realtime channel subscriptions and Riverpod's ref.invalidate lifecycle. A key dependency is the Stats Notifier component, so sequencing work to ensure that component is stable before integration testing is essential. Subscription lifecycle management — connecting on screen open and disposing on close — must be thoroughly tested across navigation scenarios to prevent memory leaks.
Debounce logic for rapid inserts adds a subtle edge case requiring dedicated QA attention. Deployment risk is low since this component is self-contained, but regression testing should cover offline/reconnect scenarios and background app states.
This component implements a reactive bridge between Supabase realtime PostgreSQL change events and Riverpod's provider invalidation system. It subscribes to the Supabase realtime channel scoped to the activities table for a specific userId, listening for INSERT events via the onActivityInserted(RealtimePayload) callback. On receiving an event, it calls ref.invalidate() on the stats-notifier provider, triggering an async refetch. The subscribe(WidgetRef ref, String userId) method should be called in initState or a ConsumerStatefulWidget equivalent, with unsubscribe() called in dispose() to prevent channel leaks.
Debounce logic (recommended: 300–500ms window) prevents redundant fetches during bulk inserts. The WidgetRef must be passed through carefully to avoid use-after-dispose crashes — consider using a mounted guard. Integration with Supabase's Flutter SDK requires the realtime channel to be properly authenticated with the user's session token.
Responsibilities
- Subscribe to Supabase realtime channel for activity insert events
- Invalidate stats notifier on receiving new activity events
- Handle subscription lifecycle (connect on screen open, dispose on close)
- Debounce rapid successive inserts to avoid redundant fetches
Interfaces
subscribe(WidgetRef ref, String userId)
unsubscribe()
onActivityInserted(RealtimePayload payload)
invalidateStats(WidgetRef ref)