Facility Service — Sync Contract
Status: populated Owner: TBD Last updated: 2026-04-17 Companion: 16 Offline & Sync · SERVICE_TEMPLATE §7
1. Offline posture
The facility-service is configuration / registry data — lifecycle changes are rare compared to clinical data. Edge nodes (field clinics) must be able to read the hierarchy and locations they are members of, but must not mutate them offline.
2. Per-aggregate policy
| Aggregate | Policy | Rationale |
|---|---|---|
| HierarchyProfile | server_authoritative | Schema of the graph; never written from edge |
| HierarchyNode | server_authoritative | Structural truth; writes require admin network |
| HierarchyEdge | server_authoritative | DAG invariant enforced centrally |
| Location | server_authoritative | Central registry |
| LocationHours | server_authoritative | |
| Bed | lww (last-writer-wins on status) | Status updates originate locally in a ward and may be applied while briefly offline |
Bed (current_patient_id) | server_authoritative | Assignment originates from inpatient-encounter service |
| ResourceCatalogItem | server_authoritative | |
| ProviderNodeMembership | server_authoritative |
3. Edge replication set
Edge nodes pull a read-only projection of:
- the subtree of the facility's hierarchy node,
- locations and beds anchored to that subtree,
- provider memberships within that subtree.
The projection is refreshed via:
- On connect: full pull
/internal/edge/snapshot?nodeId=(5m TTL). - Incrementally: subscribing to
facility.*subjects filtered by node context.
4. Conflict rules
| Field | Resolution |
|---|---|
Bed.status | LWW by updatedAt; server replays winning event as canonical |
Bed.housekeeping_status | LWW; domain re-validates state machine after merge |
| Node metadata | Server-authoritative; edge rejects locally-edited changes |
5. Referential integrity
Edge writes that reference a hierarchyNodeId or locationId that no longer exists on the server are rejected at the sync gateway with STALE_REFERENCE and the user re-fetches the registry.
6. Timing
- Configuration reads allowed offline for up to 24h.
- Bed status LWW window: 1h (beyond that, manual review).