Sync Topologies

Sync is a product decision before it is a technical decision. Choose the smallest topology that preserves user trust.

Topology Ladder

Topology	Use when	Conflict model	Complexity
No sync	single-device, private v1	none	low
Export/import	user manually moves data	import policy decides duplicates	low
Backup-only	recovery matters more than live multi-device	latest backup wins unless versioned	medium
Single-writer server sync	one device edits at a time or edits are rare	server rejects stale writes	medium
Server-authoritative mutation replay	offline writes need eventual server confirmation	server replays/rebases pending mutations	high
Subset sync	local app needs a filtered server data set	server owns truth and shape authorization	high
CRDT/collaborative sync	many peers edit the same objects concurrently	data type merge rules	very high

Mutation Replay Flow

sequenceDiagram
    participant UI as App UI
    participant Local as Local DB
    participant Queue as Mutation Queue
    participant API as Sync API
    participant Server as Server DB

    UI->>Local: Apply local change
    UI->>Queue: Persist mutation with idempotency key
    Queue->>API: Push pending mutation
    API->>Server: Validate and apply
    Server-->>API: Accepted state version
    API-->>Queue: Ack mutation
    Queue->>Local: Mark synced or apply correction

This pattern lets the UI feel instant while the server remains authoritative. It requires durable pending mutations, idempotency keys, server-side validation, and a way to rebase local optimistic state over pulled server state.

Backup-Only Flow

flowchart TD
    edit[User edits local data] --> local[(Local DB)]
    local --> export[Create backup file]
    export --> verify[Verify backup]
    verify --> store[Store user-owned copy]
    store --> restore[Restore on clean install]
    restore --> local

Backup-only is enough for many privacy-first apps. It avoids account auth, live conflict resolution, server availability, and accidental data exfiltration.

CRDT Boundary

CRDTs help when independent writers must merge without a central lock. They do not remove product design. You still need:

data types that match user intent
tombstone and compaction strategy
sync transport
storage format and migrations
user-visible conflict or history UX when automatic merge is not enough

Gotcha: If users do not collaborate on the same object, CRDTs are usually a scope trap.