Solution Design: Offline-First and Client Synchronization (Platform)
Version: 1.0
Date: 2026-03-28
Companion: SPEC.md, TECHNICAL_REQUIREMENTS.md
1. Design goals
- Local-first UX with server authority for invariants.
- Replay-safe mutations via idempotency keys.
- Explicit conflicts — no silent merge of regulated PHI.
- Aligned with Kong + JWT + module licensing patterns.
2. Logical components
| Component | Responsibility |
|---|---|
| Presentation | Forms, validation UX, sync status indicators. |
| Local store | Drafts and read models; encrypted when required. |
| Outbound queue | Pending mutations with clientMutationId, ordering metadata. |
| Sync scheduler | Triggers on online event, periodic flush, backoff on errors. |
| Auth session | Token refresh before large sync; abort if tenant mismatch. |
| Kong | Edge auth, routing, rate limits. |
| Owning service | Business rules, idempotency, audit, NATS (server-side). |
Clients do not host NATS producers.
3. High-level flow
4. Sequence: capture and sync
5. Sequence: conflict path
6. BFF (Next.js) considerations
- Server routes under
app/api/**act as trusted forwarders: attach service URLs, forward cookies or bearer tokens, and preserve idempotency headers for mutating routes. - BFF MUST NOT weaken tenant isolation; tenant is derived from session/JWT per platform baseline.
7. Registration example (reference)
For POST /v1/patients, the owning service caches successful responses keyed by tenant + idempotency token so the second identical POST returns the same body. See registration API_DOCS.md.
8. Future: dedicated sync endpoint
If volume or batching requires it, a module MAY add POST /v1/.../sync batch uploads; such endpoints MUST still enforce the same RBAC, licensing, and idempotency rules. Not required for v1 platform spec.