Skip to main content

Population Health Service — Sync Contract

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

1. Per-Aggregate Conflict Policy​

AggregateSync PolicyRationale
PopulationCohort (definition)server_authoritativeCohort DSL is complex versioned data; server is authoritative for version numbering; client may draft locally but server validates
CohortMembership (computed)server_authoritativeMembership is a server-computed projection; clients read only
DiseaseRegistryEntryserver_authoritativeDerived from upstream clinical data; no direct client mutation
RiskScore (computed)server_authoritativeComputed scores are server-only
RiskScore (override)lww (last-write-wins with audit)Manual overrides are admin-level writes; last writer wins; full audit trail required
OutreachItem statuslwwField workers may update offline; last recorded status transition wins; FSM guards applied on sync
QualityMetricSnapshotserver_authoritativeImmutable computed snapshots; never mutated post-creation
HmisExportJobserver_authoritativeServer-initiated only; no client writes
DeidentExportJobserver_authoritativeSecurity-critical; server validates de-identification before release
Facility aggregate reportappend_onlyOffline facility summaries are written once and synced; no remote override

2. Offline Facility Reports​

Facility-level aggregate reports (daily/weekly patient counts, screening compliance, immunization rates) can be generated entirely offline at district health offices using the local SQLite projection store.

Sync protocol:

  1. Local worker generates JSON aggregate snapshot signed with device keypair.
  2. On connectivity: POST /api/v1/population-health/sync/facility-reports with signed payload.
  3. Server verifies signature, validates tenant/facility scope, and merges into analytics store.
  4. Duplicate submissions (same facility + period + device) are deduplicated by (facilityId, periodKey, deviceId) composite key.
  5. Server emits population_health.facility_report.synced.v1 event after successful merge.

3. Idempotency​

All write endpoints accept Idempotency-Key header. Duplicate requests with the same key within 24 hours receive the same response as the original success.

4. Conflict Resolution for OutreachItem Offline Updates​

When an outreach worker updates item status offline and syncs later:

  1. Server checks FSM validity of the incoming transition.
  2. If transition is valid from the item's current server state, it is applied.
  3. If the server state has advanced past the incoming transition (e.g., item already completed), the sync is accepted as a no-op and the caller receives the current state.
  4. No data is silently dropped; the sync response always reflects the final authoritative state.