Sync state

Problem Context

• The product stores or edits data locally before remote acceptance, or it downloads remote content for local use.
• Sync can happen after reconnect, in the background, across devices, or after a service worker, native client, or cloud service retries queued work.
• Users need to know whether work is merely local, queued, actively transferring, accepted remotely, stuck, paused, partially synced, or blocked by conflict or validation.

Selection Rules

• Choose sync state when local and remote copies both matter and their reconciliation status affects trust, next action, or data integrity.
• Label local saved separately from remote synced until the server, service, or peer confirms acceptance.
• Show per-item status when different queue items can be queued, in progress, accepted, failed, paused, or conflicting at the same time.
• Show last successful sync time or server version when freshness or cross-device confidence matters.
• Keep failed or conflicting local work visible with retry, edit, cancel, export, or review actions.
• Use offline state when the primary condition is no connection and the question is what still works locally.
• Use progress bar when the measurable percentage is the primary useful signal, not when users need acceptance, queue, or conflict status.
• Use error state when a failed sync item has become a blocking recovery surface rather than one state in an active queue.
• Use draft state when the main concern is unpublished authoring state, even if that draft may later sync.
• Escalate from passive status to persistent recovery when sync failure affects submission, payment, legal records, medical records, file integrity, or collaboration.

Required States

• Local saved state for data persisted on the device but not yet sent.
• Queued state for work waiting for a sync attempt.
• Syncing state with scope, item count, or operation label.
• Synced state after remote acceptance.
• Partially synced state when some queue items succeeded and others did not.
• Failed sync state that preserves local work and exposes recovery.
• Retrying state that differs from idle failure.
• Paused state for user, metered-network, account, battery, or policy pause.
• Conflict-needs-review state that preserves both local and server information.
• Last successful sync timestamp or version state.

Interaction Contract

• The sync surface never upgrades local saved or queued work to synced until the remote system confirms acceptance.
• Queue-level status summarizes counts while item-level rows show which object owns each status.
• Retry acts on failed items or a clearly named queue; it does not duplicate already accepted changes.
• Cancel or remove actions explain whether they discard only queued local work or also affect the remote copy.
• Partial success remains visible until every failed, paused, or conflict item is resolved.
• Background sync updates are announced at meaningful boundaries such as queued, syncing, synced, failed, or review needed.
• The user can identify whether a problem is network retry, account sign-in, server validation, unsupported file type, policy block, or conflict.

Implementation Checklist

• Define canonical sync statuses in the data model, not just in display text.
• Store local queue entries with stable IDs, object names, timestamps, retry counts, server request identifiers, and recoverable local payloads.
• Record remote acceptance separately from local persistence and transfer completion.
• Render a compact summary plus expandable item-level rows when queues contain more than one object.
• Expose retry, cancel, export local copy, view details, and review conflict actions according to the item status.
• Use background sync, native sync queues, upload managers, or job workers only when the UI can surface their states honestly.
• Test reconnect, duplicate retry, partial server success, app restart, account sign-out, policy-blocked files, quota failure, server validation failure, and multi-device conflict.

Common Generated-UI Mistakes

• Calling local persistence Synced before remote acceptance.
• Showing only one spinner for a mixed queue of succeeded, failed, and pending items.
• Hiding failed sync work in a transient toast.
• Clearing local data after a failed retry.
• Treating server validation failure, offline mode, account pause, and conflict as the same sync message.
• Using a percentage as proof of save when server acceptance still has not happened.
• Removing the sync indicator immediately after reconnect even though queued work remains.

Critique Questions

• What exactly is local, what exactly is remote, and which copy is current?
• What event proves that this item is synced: transfer complete, server accepted, peer acknowledged, or later validation passed?
• Can users identify which queue item failed and what action fixes it?
• How does the UI represent partial success without implying the whole task is done?
• What happens to local work after app restart, account switch, retry exhaustion, or conflict?
• Does the status explain whether sync is paused, blocked, retrying, failed, or waiting for review?