Data Layer low complexity Shared Component mobile
0
Dependencies
3
Dependents
1
Entities
0
Integrations

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.

Feature: Dynamic Terminology & Labels System

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

API Contract

View full contract →
REST /api/v1/terminology-cache 6 endpoints
GET /api/v1/terminology-cache
GET /api/v1/terminology-cache/:organization_id
POST /api/v1/terminology-cache
PUT /api/v1/terminology-cache/:organization_id
DELETE /api/v1/terminology-cache/:organization_id
GET /api/v1/terminology-cache/:organization_id/timestamp