An application keeps significant state on the client and synchronises with a server. What are the architectural decisions?

The decisions

• What is authoritative. The server, always, for anything with a business invariant — but the client may be authoritative for its own pending changes until they are accepted. Leaving this undefined produces conflicts nobody can reason about.
• The conflict policy, per field. Last-writer-wins for a title, set-union for labels, server-wins for anything the server validates. Pretending one policy fits everything is the more common mistake, and the honest design declares the policy in the schema rather than burying it in merge code.
• What happens to a rejected change. An optimistic update that the server refuses must be surfaced — and silently reverting it is the behaviour users find most alarming, because their work disappeared without explanation.
• How long a client may be offline, which determines how much divergence the sync must handle and whether a full resynchronisation is ever needed.
• What the client stores and how it is evicted, since an unbounded local store eventually exhausts device storage.

The separation that keeps it maintainable

The sync engine should not know what an issue is. It moves versioned records, resolves conflicts by declared policy, and handles ordering and reconnection. If adding a field requires editing the sync engine, domain knowledge has leaked into transport, and every future field pays for it.

And the UI should not know how sync works. If a component reasons about pending mutations, the boundary is wrong.

The property that makes it worth the complexity

Interactions are instant because they are local. That is a step change in perceived quality and it is what justifies the machinery — but only if the sync is reliable enough that users stop thinking about it, which is a high bar.

A sync that occasionally loses work is worse than no local state at all, because users cannot tell which of their changes are safe.

The testing consequence

The hard cases are multi-client: two devices, one offline for twenty minutes, both editing. No lower-level test covers that, so a small number of deliberate end-to-end scenarios covering exactly those situations is necessary — and they are where the product's genuine risk lives.