Architecture One-Pager

Multiplayer Collaborative Canvas · Solution Architecture v1.0 · Microsoft Azure · Platform Architecture · 2026-10

Each document has exactly one authoritative sequencer at a time, and every client is a speculative replica of it: the client renders first and the server decides last.

Two people open the same file and start moving the same frames. Every product that has solved this — Figma, Google Docs, Notion, Canva, Miro — is judged on it without mercy: an editor that loses a stroke, double-applies a drag, or shows two people different versions of the same frame is not a slow product, it is a broken one. The difficulty is not the merge. It is that four requirements pull in opposite directions at once. The edit must feel instant, which means the client cannot wait for a server. The document must converge, which means something has to decide the order. Work done on a train with no network must survive, which means the client must be allowed to run ahead for hours. And a revoked collaborator must stop editing in seconds, which means the server must be able to say no to a socket that is already open. A design that satisfies any three of those and ignores the fourth is a demo.

Give each document exactly one authoritative sequencer — a session host that holds the document in memory, owns the socket, and assigns a monotonic sequence number to every operation — and let every client apply its own edits optimistically before that host has seen them. Acknowledge an operation only after it is durably committed to the document's own append-only log, so the acknowledgement means 'this cannot be lost' rather than 'this was received'. Make ownership a lease with a monotonically increasing epoch, and enforce the fence at the log's conditional write rather than in the router, so a host that wakes up still believing it owns the document is rejected by the store instead of corrupting the document. Separate the traffic that may be lost from the traffic that may not: presence and viewer broadcast leave through managed fan-out and are shed first under load, while edits are acknowledged or refused but never deferred. Treat disconnection as a state rather than an error, with a local operation buffer, a catch-up path chosen by how far behind the client is, and a recoverable branch for work older than the retained log. Keep every byte of asset data out of the ordering path by content-addressing it and moving it client-to-storage.

What it is, and what it is not

• One authoritative sequencer per document — not A CRDT merged peer-to-peer with no authority
• An acknowledgement means durably committed — not An acknowledgement means received
• Operations describing intent on the document graph — not Diffs of rendered output or whole-document writes
• A lease with an epoch fenced at the log — not An orchestrator that promises only one host runs
• Presence as sacrificial, unlogged traffic — not Presence as a cheap kind of edit
• Fail closed on saving, fail open on viewing — not Accept edits and hope the store comes back
• Disconnection as a declared session state — not An error toast and a page reload
• Restore as a new forward operation — not Rewriting the document's history

The decisions that are the architecture

1. One sequencer per document; clients are speculative replicas (ADR-01) — The client renders an edit before any server has seen it, and the host's order is final. That single boundary buys small intent-shaped operations, a plain append-only history, per-user undo that means what a user expects, and one implementation of the conflict rules instead of one per client platform — at the price of an authority that must be leased, fenced and failed over.
2. An operation is acknowledged on durability, never on receipt (ADR-04) — The append commits and replicates in-region before the acknowledgement is sent, which makes RPO 0 for everything the user was told was safe. The corollary is the unpopular one: when the log cannot be written the document goes read-only within 5 seconds rather than collecting edits it may lose.
3. Ownership is a lease with an epoch, fenced at the store (ADR-03) — A 15-second lease with a monotonic epoch, and the log rejecting any append carrying an older epoch, makes a brief double-ownership harmless instead of catastrophic. That is what allows a cheap lease rather than a consensus round on every operation, and it is why the 10-second re-host target is reachable.
4. Editors terminate on the sequencer; viewers and presence do not (ADR-06) — The socket and the sequencer share a process, so an acknowledgement costs one hop. Viewers and presence leave through managed fan-out, which means 1,000 viewers on a popular document consume none of the capacity of the node that orders its edits.
5. Presence is sacrificial (ADR-07) — Coalesced server-side to 10 Hz whatever the client sends, never written to the log, retained for zero seconds, and shed before anything else. It is the highest-volume and least valuable traffic in the platform, and treating it as a cheap edit is how collaborative editors end up with cursors competing with keystrokes.
6. The per-document log is the record; checkpoints are derived (ADR-09) — 900 million documents need 900 million independent logs, which is a partitioning problem rather than a topic problem — so the log is a per-document partition in a document store, not a stream broker. Checkpoints, indexes, thumbnails and search are rebuilt from it and are never backed up.
7. The session writes its own checkpoint; a verifier disagrees with it (ADR-10) — Only one implementation of document application exists on the write path, because a second one is a second set of bugs. A background verifier replays the log independently and diffs the result, which is how a one-way application bug is found before a user finds it.
8. Offline work is merged, branched, or reported — never silently dropped (ADR-12) — Buffered operations are rebased into the authoritative order under the live conflict rules while the client's version is inside the 30-day log horizon, and preserved as a recoverable branch beyond it. The one outcome the platform refuses to produce is a silent loss.
9. Capability is bound at admission and revoked on a live socket (ADR-14) — A grant change reaches the sessions it affects within 10 seconds, so revocation is a platform guarantee rather than a page reload. During a control-plane outage, open sessions continue on a 5-minute cached grace window and new admissions fail closed.
10. Convergence is a release gate, and a rollout is a drain (ADR-05) — The same operation set, delivered in randomised orders, must produce byte-identical documents, and a build that fails that does not ship. A live session never changes code version: a release drains idle documents onto the new build and leaves busy ones until they release.
11. Divergence is detected by the platform, not reported by users (ADR-17) — Clients periodically report a checksum of their state at a known sequence number, and a mismatch alerts within 60 seconds and is repaired by re-snapshotting that client. Without it, the failure with no natural alarm is found by someone whose file is quietly wrong.
12. One home region per document (ADR-16) — Active-active editing would mean two sequencers, which is the one thing this architecture forbids. Cross-region is therefore a migration with an announced pause of up to 3 seconds, and a regional failover is a declared operation with a 5-second loss window stated to users.

Why this should still be right in ten years

The document store, the real-time service, the container platform and the client framework will all be replaced inside this platform's life. These are the properties that should outlast them.

• The boundary is not a technology. "One authority per document, and the client is a speculative replica" is a statement about where decisions are made, not about which store holds the log or which service carries the sockets. Every component named in this set can be replaced without touching that sentence.
• Durability before acknowledgement survives any store. The rule that a user is told their work is safe only when it actually is does not depend on the store's API. It will outlive Cosmos DB, and it is the one rule whose violation is invisible until the day it is not.
• Fencing is older than this decade and will outlive the next. A monotonic epoch rejected by the store is the same mechanism that protects a distributed lock, a leader-elected writer and a partitioned log. Lease durations will change with network reality; the fence will not.
• Separating sacrificial traffic from durable traffic scales with the hardware. Presence will get richer — video pips, audio, spatial state — and it will stay the thing that may be dropped. A platform that has already declared its shedding order gets richer presence for free; one that has not pays for it in acknowledgement latency.
• Convergence tested by replay stays testable. Randomised operation-set replay is a property test, not a fixture. It keeps working when the operation vocabulary grows, which it will, and it is the only gate that catches the class of bug this architecture most fears.
• Intent-shaped operations age better than diffs. A log of 'reparent this object' can be interpreted by a renderer nobody has written yet. A log of pixel or geometry diffs is tied to the renderer that produced it, and makes history, undo and merge all harder in the same way.

Non-functional targets

Every figure below is a stated assumption for this design, chosen to be defensible and arguable rather than measured. A reviewer who changes one can follow it to the decision that depends on it.

Scope

In scope

• Document sessions with one authoritative sequencer, leased and epoch-fenced ownership, and automatic re-host
• An operation model over the document graph with durable commit before acknowledgement, optimistic local application, and four named conflict classes resolved identically on every client
• Presence, awareness and viewer broadcast on a separate, sacrificial path with server-side coalescing
• Reconnection and offline merge: catch-up by replay or snapshot, rebasing of buffered work, and a recoverable branch beyond the log horizon
• History: periodic checkpoints, named versions, restore as a forward operation, and per-user undo in a shared history
• Sharing, roles and link scope, with revocation effective on live sessions, plus durable anchored comments
• Out-of-band, content-addressed assets with placeholder-on-pending, scanning and derived renditions
• Divergence detection, convergence replay gates, and the operational signals that make the above measurable

Explicitly out of scope

• The client rendering engine and the editor's own interface, including how a conflict is presented
• Design-system and component semantics: the platform sequences intent it does not interpret beyond structural validity
• Prototyping playback, plugin execution, and the export pipeline's own rendering
• Billing, entitlements and seat management — the platform reads limits and never sets them
• Full-text search over document content, and the analytics estate itself
• Active-active cross-region editing, and partial loading of documents past the 500 MB ceiling

What a four-week prototype should prove

The prototype's job is to falsify the two central claims — that one leased, fenced sequencer per document is enough for correctness, and that an acknowledgement after durable commit is fast enough to feel instant — on one document shape and two clients, not to build a platform.

1. One document type, two clients, four operation kinds: create, delete, reparent, set property. No assets, no comments, no history.
2. A real append-only per-document log with a conditional write keyed on epoch, and a 15-second lease with 5-second renewal.
3. Measure acknowledgement latency at p50 and p99 under 50 concurrent editors on one document, and confirm the local echo is genuinely independent of it.
4. Kill the session host under load and measure the re-host time end to end, including client reattach and the resend of unacknowledged operations.
5. Then wake the killed host up and prove its appends are rejected: the fence, not the orchestration, is what the prototype exists to test.
6. Run the randomised convergence replay in CI from day one: 10,000 operation sets in randomised orders, asserting byte-identical state.
7. Edit offline for an hour in one client, reconnect, and check that every operation lands or is reported — count the ones that are neither.

• Two clients move the same object in the same 50 ms window, repeatedly, for ten minutes: does either client ever end up disagreeing with the log?
• One client is paused in the debugger for 40 minutes, then resumed: replay, snapshot or branch — and is the user told which?
• A client sends 2,000 operations a second: is it throttled with a retry hint, and does the other editor's acknowledgement latency change?
• Revoke the editing grant while an operation is in flight: is the operation refused, and how long did it take?
• Network-partition the host from the log while clients stay connected: does the document go read-only within 5 seconds, and does it recover without a reload?

Open risks, carried rather than hidden

The reasoning behind every component and technology choice is in the Architecture Decision Record: 17 records across 6 areas, each with the alternatives that lost and what the choice costs.