Sync Architecture — How offline-first works

Creative Job Hub (CJH) uses an offline-first model so technicians can keep working when network connectivity is poor or unavailable. This article explains the high-level architecture and lifecycle of offline operations.

High-level flow

1. Client-side action — A technician performs an action (job update, photo capture, payment, etc.). The app immediately records the action locally so the UI can remain responsive.
2. Local queue & storage — The client stores queued operations locally (the project uses IndexedDB for offline queueing). Queued items persist across app restarts so users do not lose work. :contentReference[oaicite:0]{index=0} :contentReference[oaicite:1]{index=1}
3. Background sync — When the device regains network connectivity, the client automatically attempts to upload queued operations to the server and reconcile state.
4. Server processing & acknowledgement — The server processes each item and returns status. On success the client removes the item from the local queue; on error the client retains the item and surfaces the error for retry or support.

Refresh cadence & related real-time behavior

• For map and technician visibility CJH updates locations frequently (technician locations update ~every 15 seconds; jobs refresh every ~30 seconds) to support real-time workflows. Short connectivity gaps are tolerated by the sync architecture. :contentReference[oaicite:2]{index=2}

Goals of the design

• Resilience: Let field technicians continue to record work, photos, and payments without network access.
• Responsiveness: Provide immediate UI feedback while operations are queued.
• Recoverability: Ensure queued items survive app restarts and are synchronized once online.

Implementation notes (developer-facing)

• The repository includes idb as a dependency (useful for IndexedDB-based queues). Confirm plugin/utility versions during development. :contentReference[oaicite:3]{index=3}

See also: “Queued Operations” for which items are queued, “Conflict Resolution” for how conflicts are handled, and “Sync Troubleshooting” for how to debug failed syncs.

Updated on: 10/01/2026