Document Service — Sync Contract
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 16 offline-first-and-sync
1. Offline Posture
The document-service has a mixed offline posture depending on workflow type.
2. Per-Aggregate Conflict Policy
| Aggregate / Workflow | Conflict Policy | Rationale |
|---|---|---|
DocumentTemplate | server_authoritative | Template authoring is an admin workflow; no offline editing |
DocumentTemplateVersion | server_authoritative | Publish workflow requires server validation; immutable once published |
DocumentRenderJob (sync generation) | server_authoritative | Requires live FHIR binding resolution; cannot execute offline |
DocumentRenderJob (async generation) | append_only | Client queues render request with clientMutationId; replays when online |
DocumentUpload | server_authoritative | Virus scan mandatory; no offline upload path |
DocumentArtifact (cached PDF read) | lww (client TTL) | Cached PDFs readable offline with encrypted local cache; TTL configurable per deployment |
3. Offline Capabilities by Workflow
| Workflow | Offline-capable | Notes |
|---|---|---|
| Browse published templates (cached) | Yes (read-only) | Stale-while-revalidate when online |
| Design/edit templates | No | Server is authority for template catalog |
| Generate PDF (server render) | No | Queue render request with clientMutationId; replay when online |
| View / download cached PDF | Yes | Encrypted local cache; tenant-scoped; signed URL refreshed on next sync |
| Upload scanned document | No | Virus scan requires server |
| Print from cached PDF | Device-dependent | Audit event emitted on next online sync |
4. Render Request Offline Queue
When generating a document offline, the client creates a pending DocumentRenderJob record locally with status=queued and a clientMutationId. On reconnection:
- Client replays
POST /v1/documents/render-jobswith the originalclientMutationId. - Service deduplicates by
(tenantId, clientMutationId)indocument_render_jobs. - If the job already exists (duplicate), returns the existing job status.
- If new, enqueues normally.
5. Sync Framework
The @ghasi/sync-protocol package is not used by this service for document mutations. The offline queue pattern above is custom to render job idempotency. Read-only PDF caching is handled by the client SDK's cache layer.