Skip to content

Offline Syncing

Overview

Formbird's offline syncing system ensures that documents created or modified while offline are synchronized to the server when connectivity is restored. The system uses a queue-based approach to maintain data consistency and order.

How Syncing Works

Outbound Sync (Client → Server)

When you save a document while offline:

  1. The document is saved to the local IndexedDB cache
  2. The document is added to the sync queue
  3. When connectivity is restored, the Offline Poller detects queued items
  4. Documents are sent to the server in the order they were saved
  5. Successfully synced documents are marked as processed
  6. Non-current versions are removed from IndexedDB to free up storage

Inbound Sync (Server → Client)

When receiving updates from the server:

  1. The client requests changes since the last sync
  2. New or updated documents are returned from the server
  3. Documents are cached in the local IndexedDB store
  4. Conflict resolution is applied if needed

Offline Queue

How the Queue Works

Documents waiting to sync are stored in a queue within IndexedDB. Each entry tracks:

  • The document data
  • When it was saved
  • The current sync status

Queue Status

Status Description
Unprocessed Waiting to sync
Processed Successfully synced to server
Error Sync failed (can be retried)

Processing Order

Documents are processed in the order they were saved to maintain data consistency:

  1. Oldest unprocessed entries are synced first
  2. Each document is marked as processed after successful sync
  3. Failed documents are marked with an error status
  4. Error documents can be retried

Offline Poller

The Offline Poller is a background worker that monitors the sync queue and handles synchronization.

How It Works

  • Runs in the background - Continues working even when you navigate between pages
  • Monitors the queue - Checks for documents waiting to be synced
  • Detects connectivity - Automatically resumes syncing when connection is restored
  • Prevents duplicates - Ensures each document is only synced once

Browser Support

  • Desktop browsers - Uses Shared Workers for efficient cross-tab synchronization
  • Android Chrome - Uses Web Workers (Shared Workers are being trialled but not yet standard)

The worker type is configured via the offline.android.enableSharedWorkers setting (see 012-Offline-Setup.md).

Sync Order and Conflict Resolution

Upload Before Download

The system ensures your local changes are sent to the server before receiving server updates:

  1. Push queued documents to server
  2. Wait for server to process changes
  3. Fetch updated documents from server

This ensures: - Your local changes aren't overwritten by stale server data - Conflict resolution happens with complete information - The final state reflects all changes

Conflict Handling

When the same document is modified offline on multiple devices:

  1. All versions are sent to the server
  2. The server applies conflict resolution rules
  3. The resolved document is sent back to all clients
  4. Clients update their local cache with the resolved version

Real-Time Updates

When online, documents can also be pushed to clients via WebSocket. These updates are cached locally but don't need to go through the sync queue since they came from the server.

Error Handling

Error Types

Error Type Behavior Examples
Non-Fatal Retry automatically Network timeout, server temporarily unavailable
Fatal Mark as error, stop retrying Invalid document, authentication failure

Common Issues

Issue Cause Resolution
Session expired User logged out on server Log in again
Sync not starting Poller not running Refresh the page
Documents not appearing Sync incomplete Check queue status

Configuration

Sync behavior can be configured in the application configuration. See 012-Offline-Setup.md for setup details.

Key settings: - syncPageSize - Number of documents to sync per batch - searchTimeout - Timeout for sync operations

Viewing the Sync Queue

To monitor documents waiting to be synced, use the Offline Queue template. This shows: - Documents waiting to sync - Documents that synced successfully - Documents with sync errors

See 100-Formbird-Offline-Mode.md for details on viewing the offline queue.