Terminology Service — Sync Contract

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 16 offline-first-and-sync · 02 DDD

1. Overview

The terminology-service is a shared read-mostly service. The primary sync concern is not multi-device concurrency but offline edge deployment: rural health facilities and outreach programs may need to run with no server connectivity. The sync contract covers per-aggregate conflict policy and the offline snapshot strategy.

---

2. Per-Aggregate Conflict Policy

Aggregate	Conflict policy	Rationale
Concept	server_authoritative	Coded clinical terms must be consistent across all tenants and deployments. A client cannot override a server concept. Deactivation is one-way and irreversible via API.
DrugInteraction	server_authoritative	Interaction severity is clinically significant. All decisions must reflect the current server dataset. No client-side overrides.
DrugClass	server_authoritative	Drug class assignments are derived from the licensed data source. No local modifications permitted.
DrugContraindication	server_authoritative	Contraindications are safety-critical. Server authoritative at all times.
ValueSet	server_authoritative	ValueSet composition is governed by the platform administrator. No local customization.
ConceptMap	server_authoritative	Cross-system translations are defined centrally; local overrides would produce inconsistent interop behavior.
Tenant-scoped custom Concepts	server_authoritative	Even tenant-owned concepts are mutated via server API only. No offline concept authoring.

---

3. Offline Snapshot Strategy (Edge Deployments)

For edge deployments where a permanent server connection is unavailable:

3.1 Snapshot Bundle

A terminology snapshot bundle is packaged as part of the edge service deployment. It contains:

• A PostgreSQL dump of concepts, drug_interactions, drug_classes, drug_contraindications, value_sets, value_set_concepts as of the last ETL run.
• A manifest file: terminology-snapshot-{timestamp}.json recording system versions and concept counts.

Snapshot frequency: generated after each licensed terminology ETL run (quarterly minimum).

3.2 Sync on Connectivity

When an edge instance reconnects:

1. Server publishes TERMINOLOGY.dataset.updated event with snapshot version.
2. Edge instance compares local snapshot version to server version.
3. If different: pull delta via GET /internal/terminology/snapshot/delta?since={version}.
4. Delta is applied as an upsert batch (server wins on all conflicts).

3.3 Constraints

Constraint	Description
No edge-originated mutations	Edge deployments are read-only for terminology data. All concept creates/updates must go to the central server.
No tenant custom concepts offline	Tenant-scoped custom concepts are not included in the offline snapshot. They require server connectivity.
Snapshot age limit	Edge deployments will reject snapshots older than 12 months and require a fresh ETL run.