“The app works offline and syncs later” sounds like an implementation detail. It is actually a set of product promises about when data is visible, which copy is authoritative and what happens when two people act without seeing each other.
Replication is the machinery underneath those promises. Treating it as a background transport problem postpones the hard decisions until users discover them.
Replication is not sync
Sync is a user-facing outcome. Replication is a protocol that moves and reconciles state across nodes. A system can successfully move every operation and still produce an outcome the user considers wrong.
Three questions expose the difference:
- What unit is replicated: rows, documents, operations or events?
- How is order established when clocks and connections disagree?
- When can the interface claim that a change is durable?
Name the authority
“Local-first” does not mean “the local copy always wins.” It means local state is useful without a round trip. Authority can still be centralized, shared or divided by data type.
| Model | Useful when | Cost |
|---|---|---|
| Server authoritative | Rules must be globally enforced | Optimistic changes can be rejected |
| Last writer wins | Occasional loss is acceptable | Clock and intent can diverge |
| Operation merge | Concurrent edits are common | Operations and identity must be retained |
| CRDT | Convergence is a core requirement | Data structures and tombstones become part of the product |
The right model may differ inside one product. A draft title can merge optimistically while a payment transition remains server authoritative.
Conflicts are product decisions
A merge strategy is not correct merely because it converges. Consider two offline users assigning the last available delivery slot. A deterministic winner gives every replica the same answer, but the losing user still needs a product outcome: an explanation, a replacement slot or a reversible workflow.
Conflict handling therefore has three layers:
- Detection — identify concurrent or invalid operations.
- Resolution — compute the state all replicas can accept.
- Communication — explain the result and preserve user intent where possible.
The third layer is where many technically sound systems feel broken.
State the guarantees
Document guarantees in language the product and engineering teams can both test.
Avoid “eventually consistent” as the entire specification. State what eventually means in your operating envelope, what the user may do while disconnected and what evidence marks a write as accepted.
For example:
A locally created note is immediately readable on the creating device. It is marked pending until the server has persisted its operation. Concurrent text edits converge without dropping either user’s inserted text. Permission changes may reject pending operations.
That statement is not a full protocol, but it gives the protocol a job. Replication architecture becomes much easier to evaluate once the user-visible guarantees are explicit.