Terminology Sync Service
Component Detail
Description
Orchestrates background synchronization of terminology maps to ensure the local cache stays up to date without blocking the UI. Compares the cached map version against Supabase's updated_at timestamp and triggers a refresh only when a newer version is available. Integrates with the app's connectivity-aware sync scheduling.
terminology-sync-service
Summaries
The Terminology Sync Service guarantees that organizations always see their latest approved terminology without requiring users to log out and back in. When an organization updates its custom labels in the admin panel, field users' devices pick up changes automatically in the background—eliminating support escalations caused by stale or mismatched terminology in the field. This is particularly valuable for regulated industries where label accuracy has compliance implications. The service also respects device connectivity, avoiding wasted data usage and battery drain on poor connections, which directly improves app quality scores and reduces uninstall rates.
This is a medium-complexity background service that coordinates with both the Terminology Repository and Cache Adapter. Its connectivity-aware scheduling means it has implicit dependencies on the app's network monitoring infrastructure, which must be in place before integration testing can begin. Delivery risk centers on the retry-with-backoff logic and the foreground/background lifecycle integration—both require device testing, not just unit tests. Schedule at least one round of QA with real devices in airplane-mode and spotty-connectivity scenarios.
The `schedulePeriodic(interval)` interface needs configuration management to allow tuning the sync interval per environment without a code release.
Implements a version-check-before-sync pattern: `isStale(organizationId)` compares the locally cached timestamp against the `updated_at` value fetched via `terminology-repository.fetchUpdatedAt()`, and only triggers `terminology-repository.fetchLabels()` and `terminology-cache-adapter.write()` if the server version is newer. `syncIfStale` is the standard entry point; `forceSync` bypasses the staleness check for manual refresh scenarios. `schedulePeriodic(interval)` integrates with the app's workmanager or background fetch mechanism. Failure handling should use exponential backoff with a cap; expose sync failure state so the UI can optionally surface a warning.
Avoid holding a Supabase stream open in the background to prevent battery regression—poll on schedule instead.
Responsibilities
- Poll Supabase for terminology map version changes
- Trigger cache refresh only when server version is newer
- Schedule sync on app foreground and on connectivity restore
- Report sync failures with retry backoff
Interfaces
syncIfStale(organizationId)
isStale(organizationId) → Future<bool>
forcSync(organizationId)
getLastSyncTimestamp(organizationId) → DateTime?
schedulePeriodic(interval)
Relationships
Dependencies (2)
Components this component depends on
Dependents (1)
Components that depend on this component
Related Data Entities (2)
Data entities managed by this component