sequenceDiagram
participant UI as React Component
participant Client as Sync Client
participant Store as Identity Map
participant IDB as IndexedDB
participant Outbox as Outbox Manager
participant Transport as Transport Adapter
participant Server as API Server
UI->>Client: client.update("Task", id, changes)
Client->>Client: Create transaction (clientTxId + idempotency key)
Client->>Store: Apply optimistic update
Store-->>UI: MobX reaction (UI re-renders)
Client->>IDB: Persist updated row
Client->>Outbox: Add transaction to outbox
Client->>IDB: Persist outbox entry
Outbox->>Transport: Batch and send mutations
Transport->>Server: POST /sync/mutate
Server->>Server: Validate, assign syncId, persist
Server-->>Transport: Mutation result
Transport-->>Outbox: Acknowledge transaction
Outbox->>IDB: Remove from outboxOptimistic apply: Creates a Transaction with an idempotency key, applies to the identity map, and persists to IndexedDB.
Batch send: The outbox batches transactions based on batchDelay (default 50 ms), reducing network overhead.
Server processing: Validates the mutation, assigns a syncId, persists, and broadcasts a delta to all clients.
Acknowledgment: The server responds with the assigned syncId. The outbox removes acknowledged transactions.
Deltas arrive through the WebSocket subscription when another client writes a change or the server processes your own mutation.
sequenceDiagram
participant Server as API Server
participant WS as WebSocket
participant Transport as Transport Adapter
participant Client as Sync Client
participant Rebase as Rebase Engine
participant Store as Identity Map
participant IDB as IndexedDB
participant UI as React Component
Server->>WS: Delta packet (syncActions + lastSyncId)
WS->>Transport: Receive delta
Transport->>Client: onDelta(packet)
Client->>IDB: Write batch (apply all actions)
Client->>Store: Update identity map
Client->>Rebase: Rebase pending transactions
Rebase-->>Store: Re-apply local intent
Client->>IDB: Update lastSyncId
Store-->>UI: MobX reaction (UI re-renders)Batch write: Applies all sync actions from the DeltaPacket to IndexedDB in a single atomic write.
Identity map update: Inserts create instances, updates modify them, deletes remove them.
Rebase: If affected models have pending local transactions, the rebase engine reconciles server state with local intent.
Watermark advance: Advances lastSyncId to the packet's watermark, so the next delta fetch starts from the right place.
Field-level LWW rebase resolves conflicts between server deltas and pending local transactions. Each pending transaction stores a patch and an original snapshot. Non-overlapping changes merge cleanly; overlapping fields use the configured rebaseStrategy ("server-wins", "client-wins", or "merge").
See Conflict resolution for strategies and examples.
Read and write while disconnected: the outbox queues mutations in IndexedDB until the connection returns.
sequenceDiagram
participant UI as React Component
participant Client as Sync Client
participant IDB as IndexedDB
participant Outbox as Outbox Manager
participant Transport as Transport Adapter
Note over Transport: Connection lost
UI->>Client: client.update("Task", id, changes)
Client->>Client: Create transaction
Client->>IDB: Persist optimistic update
Client->>Outbox: Queue transaction
Client->>IDB: Persist to outbox
Note over UI: UI shows changes immediately
Note over Transport: Connection restored
Transport->>Client: Reconnected
Client->>Transport: Fetch deltas after lastSyncId
Transport-->>Client: Catch-up delta packet
Client->>Client: Apply deltas + rebase
Outbox->>Transport: Replay pending transactions
Transport-->>Outbox: AcknowledgeOn reconnection, the client fetches missed deltas, then replays the outbox. Idempotency keys make retry safe, even if a mutation was sent but not acknowledged before the disconnect.
See Offline-first guide for configuration and best practices.
Each outbox transaction moves through these states:
stateDiagram-v2
[*] --> Queued: created
Queued --> Sent: transport sends
Sent --> AwaitingSync: server acknowledges
AwaitingSync --> Confirmed: delta with syncId arrives
Sent --> Queued: network error (retry)
Sent --> Failed: server rejects
Confirmed --> [*]: removed from outbox
Failed --> [*]: removed from outboxQueued (waiting to send), Sent (awaiting response), AwaitingSync (acknowledged, delta pending), Confirmed (done, removed from outbox), Failed (rejected, rolled back). Network errors move back to Queued for retry.