Define offline business requirements and source of truth

Offline mode and local database synchronization must protect business continuity, data integrity, and user trust. The architecture begins with workflows that must remain useful without reliable connectivity.
Treat the local database as the application’s readable source of truth. Network responses update that database, while screens observe committed local state instead of depending directly on remote calls.
Classify offline workflows
List every critical journey and decide whether it supports offline reading, offline writing, queued submission, or online-only execution. Explain unavailable actions before users begin them.
A field inspection can usually store forms and photos locally. A bank transfer may require an online authorization because delayed confirmation could misrepresent a financial commitment.
| Workflow class | Offline behavior | User promise |
|---|---|---|
| Read cached data | Show local records with freshness state | Available with a known last-sync time |
| Queue noncritical write | Store operation for later delivery | Accepted locally, pending synchronization |
| Lazy critical write | Commit locally and reconcile | Protected against loss, subject to conflict rules |
| Online-only transaction | Disable or defer action | No false confirmation without server acceptance |
Define data ownership and freshness
For each entity, name the authoritative server, local representation, synchronization direction, retention window, freshness expectation, and fields that users may change while offline.
Android’s offline-first guidance recommends a local data source for repositories that use network resources. Higher layers read locally while repository logic coordinates network updates.
Use these actions to define data ownership and freshness:
- Account and tenant boundaries for every locally stored record.
- Last successful synchronization time and server revision.
- Fields available for offline viewing or editing.
- Maximum acceptable staleness for each workflow.
- Retention and deletion requirements for lost or retired devices.
- Server rules that remain authoritative after reconnection.
Specify the offline synchronization contract

Define stable identifiers, server revisions, timestamps, tombstones, pagination cursors, idempotency keys, and conflict responses. Document how clients recover after missing many changes.
Do not use connectivity status as proof that a request will succeed. Networks can disappear after a check, proxies can retry requests, and server responses can be lost.
Follow this sequence to specify the synchronization contract:
- Assign globally unique client operation identifiers.
- Return a server revision after every accepted mutation.
- Expose delta queries from a durable synchronization cursor.
- Represent deletions with tombstones until all clients can observe them.
- Define full-resync conditions when cursors expire.
- Version the contract independently from the mobile release.
Model user-visible states
Expose whether data is local, synchronized, stale, queued, retrying, conflicted, rejected, or blocked. Users need actionable state rather than a generic spinning indicator.
Show the last successful sync and affected records. Preserve user input after failure, explain corrective steps, and never present queued work as server-confirmed completion.
Version contract compatibility deliberately
Define which client and server contract versions can exchange mutations, deltas, tombstones, conflicts, and schema-dependent fields safely.
Reject incompatible operations visibly instead of interpreting unknown fields or silently discarding data that an older client cannot preserve.
Define full-resync boundaries
Specify when expired cursors, corrupt state, tenant changes, or contract upgrades require a snapshot, rebase, or complete local reset.
Protect unsynchronized work before replacement. A full refresh must not erase accepted local actions merely because remote history is unavailable.
Design local database schema and durable operation queue

The local schema must support reads, pending mutations, retries, conflicts, migrations, and recovery. Keep synchronization metadata separate from business fields whenever that improves maintainability.
Use transactions so a business change and its queued operation commit together. If the app crashes between them, the local record and outbox must still remain consistent.
Create a durable outbox
An outbox records each mutation before network delivery. The synchronization worker claims eligible rows, sends them, records results, and retries only failures that can succeed later.
Store intent rather than an opaque request when possible. Structured operations support migrations, conflict inspection, selective retry, privacy filtering, and deterministic tests.
CREATE TABLE sync_outbox (
operation_id TEXT PRIMARY KEY,
entity_type TEXT NOT NULL,
entity_id TEXT NOT NULL,
operation_type TEXT NOT NULL,
payload_json TEXT NOT NULL,
base_revision TEXT,
state TEXT NOT NULL,
attempt_count INTEGER NOT NULL DEFAULT 0,
next_attempt_at INTEGER,
created_at INTEGER NOT NULL
);Protect queue ordering and dependencies
Store operations independently from interface state and preserve dependencies when one local action requires the server result of another.
Do not assume creation order alone defines safe delivery. Model entity relationships, required identifiers, and transaction boundaries explicitly.
Use these controls for a durable operation queue:
- Persist operations before confirming local success
- Assign stable identifiers exactly once
- Record dependencies between related mutations
- Separate retry state from business payloads
- Retain bounded diagnostics after failure
Recover the queue after interruption
Restart workers from persisted states after process death, application upgrades, device reboot, or an interrupted database transaction.
Reconcile any operation whose request may have reached the server before sending it again, using the original idempotency identifier.
Track synchronization metadata and durability

Store the server revision, local modification time, synchronization state, and deletion marker with each entity. Avoid trusting device clocks to order changes across different devices.
Use server-issued revisions or version vectors when ordering matters. Device timestamps remain useful for diagnostics and user display, but clock drift can corrupt conflict decisions.
| Field | Purpose | Rule |
|---|---|---|
| server_revision | Detect changed remote state | Issued and compared by the server |
| sync_state | Drive interface and worker behavior | Use an explicit finite set of states |
| operation_id | Deduplicate repeated delivery | Generate once and persist before sending |
| deleted_at | Propagate deletion safely | Retain tombstone through synchronization window |
| last_error_code | Support repair and diagnostics | Store bounded structured values |
Choose database durability settings
SQLite write-ahead logging allows readers and a writer to proceed concurrently, but it introduces WAL and shared-memory files that must be handled correctly during backup and recovery.
Select journal mode, checkpoint behavior, transaction boundaries, encryption, and backup procedures through device tests. Defaults may differ across frameworks, database wrappers, and operating systems.
Use these actions to choose database durability settings:
- Enable foreign keys and verify constraints after migrations.
- Use transactions for entity and outbox changes.
- Keep long-running reads from delaying checkpoints unnecessarily.
- Back up the database with its required journal state.
- Encrypt sensitive data using supported platform storage and key management.
- Test recovery after process termination during a transaction.
Plan migrations before release
Every mobile version may encounter databases created by earlier releases. Test forward migrations across supported paths and define whether rollback, repair, or controlled reset is safe.
Never discard unsynchronized operations during migration. Copy or transform queued payloads, verify row counts and constraints, and retain diagnostic evidence when repair fails.
Follow this sequence to plan migrations before release:
- Create fixtures for each supported historical schema.
- Run migrations with realistic database sizes.
- Verify entities, outbox rows, tombstones, and cursors.
- Interrupt migration at controlled failure points.
- Confirm restart behavior and repair messaging.
- Measure migration duration on low-tier supported devices.
Synchronize changes with idempotency, deltas, and retries

Synchronization is a protocol, not a background refresh. It must tolerate duplicate delivery, lost responses, reordered operations, partial batches, authentication changes, and repeated app termination.
Make every mutation idempotent by operation identifier. A retry with the same identifier returns the original outcome instead of creating another order, payment, inspection, or activity record.
Process an upload batch safely
Claim a bounded set of eligible outbox rows in deterministic order. Mark them in flight transactionally, then send the batch with operation identifiers and base revisions.
On response, commit accepted server revisions, rejected reasons, and retry schedules in one local transaction. Release abandoned in-flight rows after a safe lease expires.
POST /sync/mutations
Idempotency-Key: 8f61a9d2-...
{
"cursor": "rev-28410",
"operations": [
{"id": "op-901", "entity": "inspection-44", "baseRevision": "17"}
]
}Download deltas from a durable cursor
Request changes after the last committed cursor and apply each page in a transaction. Advance the cursor only after the page is durably stored and validated.
A cursor should represent server ordering, not the device’s current time. Expired cursors require an explicit snapshot or rebase flow that preserves unsynchronized local work.
Follow this sequence to download deltas from a durable cursor:
- Upload eligible local operations or reserve their base revisions.
- Request a bounded page after the committed cursor.
- Validate tenant, schema version, identifiers, and permissions.
- Apply entities and tombstones in a local transaction.
- Advance the cursor after the transaction commits.
- Repeat until caught up, then reconcile remaining uploads.
Retry and constrain offline synchronization safely

Retry network timeouts, temporary unavailability, throttling, and selected server errors with exponential backoff and jitter. Respect server retry guidance when it is trustworthy.
Do not retry invalid payloads, authorization failures, schema incompatibility, or resolved business rejection indefinitely. Move them into a visible repair state with structured diagnostics.
| Failure | Action | User state |
|---|---|---|
| Timeout or disconnected | Retry with backoff and idempotency | Queued or retrying |
| Rate limited | Honor retry window | Delayed |
| Authentication expired | Refresh credentials or require sign-in | Action required |
| Validation rejected | Stop automatic retry | Needs correction |
| Revision conflict | Run conflict policy | Conflict review |
| Cursor expired | Rebase from snapshot | Resynchronizing |
Constrain background work
Run synchronization through platform-supported persistent scheduling. Apply battery, data, connectivity, authentication, and business urgency constraints instead of maintaining an uncontrolled polling loop.
Prevent concurrent workers from sending the same rows unless the protocol tolerates it. Use leases, unique work, database claims, and server idempotency as layered protection.
Bound retries by urgency and device cost
Set maximum attempts, elapsed time, batch size, and backoff according to business urgency, connectivity, battery, data usage, and provider guidance.
Pause work when authentication, schema, authorization, or business validation requires intervention. Repetition cannot correct a permanent rejection.
Use these controls for bounded synchronization work:
- Classify failures before scheduling retries
- Honor trusted server retry windows
- Cap attempts and total elapsed time
- Limit batches by device conditions
- Expose exhausted work for repair
Preserve fairness across queued records
Prevent one failing operation from blocking unrelated records indefinitely. Isolate ordered dependencies while allowing independent work to continue safely.
Monitor the oldest eligible operation, not only aggregate throughput. A healthy average can hide a record that never receives service.
Resolve conflicts, protect data, and communicate state

Conflicts occur when local work is based on a server revision that has changed. Resolution must reflect business meaning, not a universal timestamp rule.
Last-write-wins can suit low-risk preferences, but it can silently discard important business changes. Inventory, approvals, schedules, pricing, and regulated records often need explicit policies.
Choose conflict rules by entity
Define whether each field is server-owned, client-owned, mergeable, append-only, or manually reviewed. Include deletion conflicts and relationships, not only updates to scalar values.
Keep both versions and their provenance until resolution completes. A conflict interface should show meaningful differences, ownership, timestamps, and consequences without exposing internal metadata unnecessarily.
| Data type | Candidate strategy | Risk control |
|---|---|---|
| User preference | Last accepted value | Show current state after sync |
| Append-only activity | Union by unique identifier | Reject duplicate operation IDs |
| Numeric inventory | Server transaction | Prevent client-side overwrite |
| Editable form | Field-aware merge | Show unresolved changed fields |
| Approval record | Server authority | Preserve immutable audit history |
Protect local business data
Minimize data stored on devices, scope every query by tenant and user, encrypt sensitive records, secure keys through platform facilities, and remove data after access revocation.
Offline access complicates revocation because a disconnected device cannot receive immediate policy changes. Define session lifetime, data expiry, reauthentication, remote wipe support, and risk-based limitations.
Use these actions to protect local business data:
- Encrypt databases, files, and sensitive queue payloads.
- Keep authentication secrets outside ordinary application tables.
- Redact personal data from logs and synchronization errors.
- Verify tenant scope before applying every server delta.
- Expire sensitive cached data according to business policy.
- Audit export, backup, restore, and device-transfer behavior.
Design honest synchronization feedback

Show pending counts, failed operations, conflict status, last successful sync, and whether displayed data may be stale. Avoid a single global badge when only some records failed.
Provide retry and repair actions where users can succeed. Preserve submitted work, explain rejected fields, and identify actions that require connectivity or administrator intervention.
Follow this sequence to design honest synchronization feedback:
- Confirm local save immediately when durability succeeds.
- Label queued work separately from server-confirmed work.
- Show record-level failures near affected workflows.
- Offer retry after transient failures.
- Guide correction for permanent validation errors.
- Escalate unresolved conflicts without deleting either version.
Evaluate managed synchronization services
Managed databases can reduce protocol work, but their conflict semantics and offline query limits still require product review. Firebase documents automatic cache synchronization and last-write-wins for same-document changes.
Verify platform support, cache behavior, security rules, indexing, transactions, observability, export, pricing, and exit options. A convenient SDK does not replace domain-specific conflict policy.
Separate local success from server confirmation
Tell users when work is saved locally, queued, transmitted, accepted, rejected, conflicted, or waiting for a required sign-in.
Use record-level status when outcomes differ. A global success indicator can misrepresent failed changes hidden among completed operations.
Evaluate managed services against exit risks
Test offline queries, conflict behavior, security rules, transactions, observability, export, pricing, schema evolution, and supported device conditions before adoption.
Document how data and pending operations can leave the service. Convenience should not make recovery or future migration impractical.
Test failure recovery and operate synchronization in production

Test the system by breaking it at controlled boundaries. Ordinary happy-path tests cannot prove durability after process death, duplicate requests, corrupted payloads, expired sessions, or partial synchronization.
Build deterministic fixtures and a controllable synchronization server. Record seeds, device state, database version, cursor, queued operations, injected failure, and expected recovery outcome.
Create a failure matrix
Interrupt before local commit, after local commit, during upload, after server acceptance, during response, while applying deltas, and before cursor advancement. Restart after each point.
Repeat across supported operating systems, database versions, low storage, low memory, clock drift, long offline periods, large queues, and multiple devices editing related data.
| Failure injection | Expected property | Evidence |
|---|---|---|
| Lost response after server commit | No duplicate business action | Same operation ID returns prior result |
| Process death during delta apply | No partial page | Transaction rolls back or fully commits |
| Expired credentials | No unauthorized retry loop | Queue pauses and requests sign-in |
| Database migration interruption | No lost pending work | Restart recovers or enters safe repair |
| Conflicting edits | Policy is deterministic | Both versions and decision are auditable |
Monitor synchronization health
Measure queue age, queue depth, success latency, retry rate, permanent failure rate, conflict rate, cursor lag, full-resync frequency, data volume, battery impact, and affected users.
Aggregate diagnostics without collecting unnecessary content. Correlate operation identifiers across device and server while protecting tenants, personal data, credentials, and regulated information.
Use these actions to monitor synchronization health:
- Alert on growing oldest-operation age, not only error count.
- Separate transient retries from permanent rejection.
- Track synchronization health by app and operating-system version.
- Detect one tenant or entity dominating failure volume.
- Measure recovery completion after backend incidents.
- Retain bounded diagnostics for reproducible support investigations.
Prepare operational runbooks
Document how support diagnoses a stuck queue, conflict, expired cursor, migration failure, authentication problem, or backend incident without instructing users to erase unsynchronized work.
Provide safe export, repair, rebase, and escalation procedures. Data reset should be a controlled last resort after pending operations are preserved or deliberately abandoned.
Follow this sequence to prepare operational runbooks:
- Identify the user, tenant, device, app version, and database version.
- Capture queue statistics and bounded diagnostic codes.
- Confirm authentication and backend health.
- Determine whether retry, correction, conflict review, or rebase applies.
- Preserve pending operations before repair.
- Verify synchronization and user-visible state after recovery.
Review the architecture with production evidence
Revisit synchronization limits after real usage reveals queue sizes, offline duration, conflict patterns, support burden, and device constraints. Update contracts and migrations through backward-compatible releases.
Align this operating model with the broader native versus cross-platform architecture decision so framework choices preserve required database and background-work guarantees.
Audit local data when access or device ownership changes
Define what happens when a user signs out, loses authorization, changes role, leaves the organization, or transfers a managed device.
Remove inaccessible local data and credentials without discarding pending work that an authorized recovery process must preserve. Record the policy by data class.
Use these actions to audit local data when access or:
- Revoke active credentials and refresh tokens.
- Stop new synchronization attempts.
- Preserve approved recovery evidence.
- Delete local data after authorization review.
Test the lifecycle on offline devices. A client that cannot contact the server still needs an expiration strategy for sensitive data and cached permissions.
When the device reconnects, the server should reject revoked access, reconcile allowed pending operations, and avoid restoring data the user can no longer view.
Connect synchronization to API contract governance
Separate the related internal references with operational context before moving from client behavior to server-side integration design.
For server-side contracts and ownership, read our custom API and third-party integrations playbook.
Conclusion

Reliable offline mode is a data architecture and operating capability, not a network-status feature or a local cache added after development.
Define authority, durability, synchronization, conflict, security, feedback, and recovery before disconnected work carries important customer or operational consequences.
Preserve every accepted user action
Commit work locally before acknowledging it, persist operation identifiers, and keep pending changes durable across application restarts, process death, and device reconnection.
Upload bounded batches idempotently, apply server deltas transactionally, and advance durable cursors only after local validation and commit succeed.
Use these controls across the synchronization lifecycle:
- Define authoritative data and offline permissions
- Persist operations before reporting local success
- Classify retryable and permanent failures
- Resolve conflicts with entity-specific policies
- Show pending, stale, failed, and confirmed states
Operate recovery as a product workflow
Monitor queue age, failure classes, conflict rates, duplicate prevention, cursor health, and affected user journeys instead of reporting connectivity alone.
Provide visible repair states, structured diagnostics, safe retry, reauthentication, conflict review, and full-resync procedures that preserve unsynchronized work.
Review security and contracts continuously
Reassess retention, encryption, access revocation, migrations, and API compatibility when workflows change. Include those checks in the offline app development scope.
A trustworthy offline application remains understandable during failure, recoverable after disruption, and honest about which data has reached authoritative systems.
Validate on representative devices
Test constrained storage, older operating systems, process termination, clock drift, intermittent networks, revoked access, and long periods without synchronization.
Repeat recovery after schema and contract changes. Laboratory connectivity alone cannot prove durability under the conditions users actually experience.
FAQ
These answers summarize common offline design decisions; security, regulatory, data-loss, and transactional requirements may require stricter controls validated against representative devices and failures.
Should the local database be the source of truth?
For offline-first repositories, screens should normally read committed local state. Repository logic synchronizes network data into that source while preserving clear server authority rules.
Is last-write-wins safe for every conflict?
No. It can suit low-risk preferences, but it may discard important edits. Choose policies by entity, field ownership, transaction semantics, and audit requirements.
How do retries avoid duplicate transactions?
Persist one operation identifier before sending. The server stores or recognizes that identifier and returns the original outcome when the same operation is delivered again.
When should an app require connectivity?
Require connectivity when the server must authorize current state, reserve scarce resources, enforce immediate policy, or confirm a transaction that users cannot safely treat as pending.
What should users see while offline?
Show available local data, freshness, queued changes, last successful sync, affected failures, conflicts, and actions requiring connectivity. Never label a local queue entry as server-confirmed completion.
How should synchronization cursors be stored?
Store them durably with the local dataset, advance them only after successful application, and design server cursors to remain valid across retries and pagination.
What happens when the local schema changes?
Use versioned migrations, preserve pending operations, test interrupted upgrades, validate rollback limits, and prevent a new client from corrupting older synchronized data.
Should every record be available offline?
No. Select data by user task, sensitivity, freshness, storage, retention, and device risk. Minimize local copies and remove data when access ends.
How should deleted records synchronize?
Use explicit deletion markers or server events with retention rules so offline clients can distinguish deletion from a record that was never downloaded.
Which synchronization metric should be reviewed first?
Start with the age and count of pending operations, then examine failure classes, conflict rate, completion latency, duplicate prevention, and affected user journeys.











Leave a Reply