Terminology Local Cache Adapter
Component Detail
Description
Persists terminology maps to device-local storage (e.g., SharedPreferences or Hive) so that labels are available immediately on app launch and when offline. Stores one map per organization, keyed by organization ID, along with a cache timestamp for staleness checks.
terminology-cache-adapter
Summaries
The Terminology Local Cache Adapter ensures that every user sees correct, organization-specific language immediately on app launch—even before any network request completes and even when the device is fully offline. This eliminates the 'flash of wrong terminology' problem where generic or raw key strings briefly appear, which erodes trust in enterprise deployments where branding precision matters. For field users who operate in connectivity-challenged environments, this component is the difference between a functional and a broken experience. Its ability to store maps per organization also enables seamless multi-tenant scenarios where a user switches between organizations on the same device.
This is a low-complexity component with no external service dependencies, making it one of the lowest-risk deliverables in the terminology subsystem. It should be built and unit-tested first since the Cache Adapter is a dependency of both the Repository and the Sync Service. The primary decision to resolve before implementation starts is the local storage technology choice—SharedPreferences is simpler but has size limits; Hive offers better performance for larger maps. Document this decision in the sprint as it affects the setup requirements for device testing.
The `evictAll()` interface must be wired into the account logout flow, which requires coordination with the authentication team.
Provides a key-value storage abstraction over a device-local persistence layer (SharedPreferences or Hive box). Each organization's map is serialized to JSON and stored under a namespaced key (e.g., `terminology_map_{organizationId}`), with the cache timestamp stored under a companion key (`terminology_ts_{organizationId}`). `write(organizationId, map, timestamp)` serializes and persists atomically where the storage layer allows. `read(organizationId)` deserializes and returns null on cache miss.
`has(organizationId)` enables fast existence checks before a full read. `evict(organizationId)` removes both the map and timestamp keys. Wrap all storage calls in try/catch to gracefully handle storage quota errors and return null rather than throwing. The adapter should be injected via Riverpod to allow substitution with an in-memory implementation during tests.
Responsibilities
- Write a terminology map to local storage keyed by organization ID
- Read a cached terminology map for a given organization ID
- Store and retrieve the last-cached timestamp per organization
- Evict stale or superseded cache entries on demand
Interfaces
write(organizationId, map, timestamp)
read(organizationId) → Map<String, String>?
readTimestamp(organizationId) → DateTime?
evict(organizationId)
evictAll()
has(organizationId) → bool
Relationships
Dependents (3)
Components that depend on this component
Related Data Entities (1)
Data entities managed by this component