Offline And Sync
Offline-safe capture is one of the most important promises in the mobile app. A user should be able to save an insight confidently, even when the connection is poor, and trust the system to sync that record later.
Mobile reliability model
The app should persist writes locally first, preserve queue state across interruptions, and retry sync without making the user feel like their work is at risk.
What this page answers
- what users should experience while offline
- where sync failures usually happen
- what QA should verify before release
Save and sync lifecycle
Failure-state map
User-facing guarantees
The user should not wait on a round trip to know their insight was captured.
Queued items should survive app restarts, weak networks, and interrupted sessions.
Offline UI should communicate delay, not failure, unless the record is truly broken.
When connectivity returns, the app should reconcile cleanly without duplicates or corruption.
High-risk checkpoints
| Checkpoint | Why it is risky | What to verify |
|---|---|---|
| Auth restore | stale sessions can block queue recovery or send users to the wrong screen | reopen the app after time away and confirm pending state still exists |
| Form recovery | partial capture state can disappear if the app is interrupted mid-flow | background or close the app during capture and confirm recovery behavior |
| Queue persistence | local storage bugs can silently drop pending items | create records offline, relaunch, and confirm queued count remains correct |
| Retry behavior | aggressive retries can create duplicates or confusing status | reconnect repeatedly and confirm one logical record appears in admin |
| Cached reads | stale cached views can make the app look broken after reconnect | confirm fresh data eventually replaces older cached values |
QA walk-through
- Create a new insight while online and confirm the save feels immediate.
- Repeat the same flow with the device offline and confirm the UI still communicates success.
- Close and reopen the app before reconnecting; the pending item should remain recoverable.
- Restore connectivity and confirm the queue drains cleanly.
- Verify the synced item in the admin control plane without duplicates, corruption, or missing context.
Keep changes small in offline, sync, and auth flows unless there is a deliberate migration plan. These areas carry a higher-than-normal risk of breaking core product guarantees.
Source repositories
Detailed implementation docs live in the mobile repo and should be treated as canonical when code and site docs differ.
docs/ARCHITECTURE.mddocs/KNOWN-ISSUES.mddocs/API-INTEGRATION.md