Summary Offline Cache
Component Detail
Description
Local persistence store (using Hive or SQLite via drift) that serialises computed AnnualSummary objects to device storage. Enables offline viewing of the last generated summary without network access, honouring the implementation note that summaries must work offline.
summary-offline-cache
Summaries
The Summary Offline Cache ensures that peer mentors can access their annual impact summary at any time, even without an internet connection — a capability that is especially important for mentors working in schools, community centres, or other environments with unreliable connectivity. By storing the most recently computed summary directly on the device, the platform delivers a consistent, high-quality experience that does not degrade when network conditions are poor. This offline reliability is a meaningful differentiator: it signals to mentors that the platform respects their time and circumstances, strengthening trust and satisfaction. The cache also reduces repeated API calls to Supabase, lowering infrastructure costs at scale as the mentor base grows.
The Summary Offline Cache is a low-complexity component with no external dependencies, making it a safe candidate for early development and an ideal stub target for teams working on the repository and BLoC layers in parallel. The primary delivery risk is the choice of local storage technology — Hive versus drift (SQLite) — which should be decided based on the existing app storage strategy to avoid introducing a second persistence library. The serialisation format for AnnualSummary objects must be agreed before implementation, as changes post-launch will require a migration strategy. Testing should cover write-then-read round trips, stale detection based on configurable maxAge, deletion on logout, and clearAll for data reset scenarios.
Confirm that the cache storage path is excluded from iCloud and Google Drive backups if the data is considered sensitive or regenerable.
The Summary Offline Cache is a thin key-value persistence wrapper over either Hive (box-based, no schema) or drift (SQLite, type-safe schema). The key schema should be a composite of mentorId and period identifier to support multiple mentors or period slots on a shared device. The write and read methods handle AnnualSummary serialisation — if using Hive, register a TypeAdapter; if using drift, define a Dao with a summaries table. isStale computes the difference between the current UTC time and the stored write timestamp, comparing it against the provided maxAge Duration — expose this threshold as a constructor parameter or environment config to allow tuning without code changes.
delete removes a single entry by key; clearAll iterates all stored keys and deletes them, suitable for logout flows. Ensure all methods are Future-based and handle storage exceptions (e.g., disk full, corrupted box) by returning null from read and rethrowing from write so the repository layer can decide on fallback behaviour. Keep the implementation free of BLoC or UI imports to maintain clean layer separation.
Responsibilities
- Persist serialised AnnualSummary objects to local device storage
- Retrieve cached summary by mentor ID and period key
- Enforce cache expiry policy (e.g., stale after 24 hours)
- Clear cache entries on logout or data reset
Interfaces
write(key: String, summary: AnnualSummary): Future<void>
read(key: String): Future<AnnualSummary?>
isStale(key: String, maxAge: Duration): Future<bool>
delete(key: String): Future<void>
clearAll(): Future<void>
Relationships
Dependents (2)
Components that depend on this component