Statistics Cache Manager
Component Detail
Description
In-memory cache for statistics query results with a 15-minute TTL to avoid repeated heavy Supabase queries. Cache is keyed by (coordinatorId, periodHash) and invalidated explicitly on data mutations (new activity registered, approval granted).
stats-cache-manager
Summaries
The Statistics Cache Manager is a performance infrastructure component that prevents the mobile app from repeatedly hammering the Supabase database with expensive statistics queries. By caching results for 15 minutes, it ensures fast, responsive statistics screens for users while significantly reducing database read load and associated Supabase costs. For an application where statistics screens may be visited multiple times per session by coordinators reviewing their dashboards, this cache directly translates to a better user experience and lower infrastructure costs at scale. Shared across all statistics features, it provides consistent performance characteristics throughout the statistics product surface without requiring each feature team to implement their own caching strategy.
Statistics Cache Manager is a low-complexity shared infrastructure component with no external dependencies, making it an early, low-risk deliverable. It should be implemented before stats services that depend on it (coordinator-stats-service, personal-stats-service). The TTL of 15 minutes is a product decision that may need revisiting based on user feedback — document this as a configurable constant rather than a magic number so it can be adjusted without code changes. Testing requirements include unit tests for TTL expiry, explicit invalidation, coordinator-keyed invalidation, and cache hit/miss metrics.
Key integration consideration: mutation paths (new activity registered, approval granted) must call invalidateByCoordinator to prevent stale data — ensure this is documented and enforced in code review. No deployment complexity.
Statistics Cache Manager is a shared mobile infrastructure component implementing a generic in-memory TTL cache. The interface is fully generic (get
getCacheStats() returns CacheStats with hit count, miss count, and current entry count for debug tooling. Internally, entries should be stored as (value, expiresAt) tuples in a Map
Responsibilities
- Store and retrieve cached stats results by cache key
- Enforce 15-minute TTL on all cached entries
- Invalidate cache entries on explicit request or on known mutation events
- Provide cache hit/miss metrics for debugging
Interfaces
get<T>(String cacheKey) → T?
set<T>(String cacheKey, T value, {Duration ttl = const Duration(minutes: 15)})
invalidate(String cacheKey)
invalidateByCoordinator(String coordinatorId)
invalidateAll()
buildCacheKey(String coordinatorId, StatsPeriodFilter filter) → String
getCacheStats() → CacheStats
Relationships
Dependents (2)
Components that depend on this component