Patient Portal 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 patient-portal-service is a BFF (Backend-for-Frontend). It does not own clinical records. Its offline/sync concerns are limited to portal-owned aggregates and caching strategy for upstream FHIR projections.
2. Per-Aggregate Conflict Policy
| Aggregate | Conflict policy | Rationale |
|---|---|---|
| PortalAccount | server_authoritative | Account status, MFA settings, and suspension must always reflect server truth. Client cannot override. |
| ProxyDelegation | server_authoritative | Delegation grants and revocations have legal/compliance significance. No client-side conflict resolution. |
| DemographicsUpdateRequest | server_authoritative | Requests are submit-once; status transitions are driven by clinical staff, not by client sync. |
| PortalAccessEvent | append_only | Audit log. Events are appended; never updated or deleted. Duplicates are idempotency-keyed on id. |
| ExportJob | server_authoritative | Job state managed exclusively by server; client polls. |
| FHIR read projections (cached) | server_authoritative | Upstream services own clinical data. Portal cache is a read-through cache; upstream always wins. |
3. Offline Posture
The patient portal does not support offline mutation. The portal is a patient-facing consumer channel, not a clinical workstation. All mutations (appointment requests, refill requests, demographics updates) require an active server connection to enforce:
- Real-time authorization checks
- Result release policy enforcement
- Concurrent delegation validity checks
Read-only offline caching (mobile app): The React Native mobile app may cache the last-fetched chart sections, appointment list, and lab results for display-only purposes when offline. This cache is strictly read-only. Mutations attempted while offline are queued and submitted when connectivity is restored, with a conflict check on submission.
4. Mobile Offline Queue
When the mobile app is offline, the following mutations may be queued:
| Mutation | Queue behaviour |
|---|---|
| Appointment request | Queued; submitted when online; server checks slot availability at submit time |
| Medication refill request | Queued; submitted when online |
| Demographics update request | Queued; submitted when online |
Queued mutations older than 24 hours are discarded with a user notification. No clinical mutations are queued.