Storage & collaboration, an interactive architecture walkthrough
Real-time collaborative document editing: how the architecture works
How collaborative editors keep several people's edits in sync: ordering operations, OT versus CRDT, snapshots and live cursors.
This is a learning explainer based on public engineering writing and general design practice. It is simplified, it is not the actual architecture of any company, and it may be inaccurate.
Interactive diagram
Overview
A collaborative editor lets several people change the same document at once and see each other's cursors. Each client applies its own edits immediately, then sends them to a server that gives every document a single ordered history. Concurrent edits are reconciled by one of two families of algorithm: operational transformation (OT), where the server rewrites each operation to account for the ones accepted before it, or CRDTs, where every piece of content has an identity so edits merge in any order. Presence (who is here, where their cursor is) travels on a separate, disposable channel.
Trade-offs and what changes at scale
OT with a central server is compact on the wire but its transformation rules are easy to get wrong, and offline editing means transforming a long backlog; CRDTs make offline and peer-to-peer natural but keep per-character metadata (identifiers and markers for deleted text) that implementations must compact. Figma has written that it chose a server-ordered, property-level last-writer-wins model instead, because its data is objects with properties rather than text. Single-owner documents keep ordering simple but make one very hot document a single-process limit, and failover must avoid two owners. Snapshots bound load time, and long operation logs cost storage. Comments, suggestions and rich-text schema changes add more cases than are shown here. This is a simplified teaching model based on public information, not any product's actual architecture.
How it works, step by step
The walkthrough above, as text. Each step lights up the components named under it.
A user opens a document. The client connects over a WebSocket, so the server can push other people's edits without being asked. The gateway authenticates the connection and checks what the user may do with the document.
The gateway asks the Session Router which process owns this document. At any moment one owner orders all edits for a document, so there is a single sequence of changes to agree on. If the owner dies, the router assigns another and clients reconnect.
The owner loads the latest snapshot from the Snapshot Store and the operations logged after it, then sends the client the document and its current revision number. Starting from a snapshot keeps opening a long-lived document quick.
The user types. The client applies the edit locally at once, so typing never waits on the network, and sends it as an operation tagged with the revision it was based on. It keeps one operation in flight and buffers the rest.
The owner receives the operation, which may be based on an older revision than the latest. In an operational transformation design it transforms the operation against the changes accepted since that revision, so that the intent (insert here, delete that) still makes sense. A CRDT design instead gives every inserted item a unique identity, and the merge needs no transformation but carries more metadata per character.
The transformed operation is appended to the Operation Log with the next revision number before it is acknowledged. Because the log is the ordered history, it also provides version history and recovery after a crash.
The owner acknowledges the sender and broadcasts the accepted operation. The gateway pushes it to every other connected client, and each client transforms its own pending operations against it, so all copies converge on the same text.
Cursors and selections travel separately from edits. They are frequent, cheap to lose and meaningless after a short while, so they skip the log of accepted edits and are held in a store with an expiry.
The Presence Service fans cursor updates out to the other people in the document. Updates are throttled and a dropped one is simply replaced by the next. A client that stops sending is shown as offline after a timeout.
In the background the Snapshotter reads old operations and writes a new snapshot, so the log tail stays short. Old operations can then be kept for history or archived, depending on retention.
A client that lost its connection reconnects with the last revision it saw. The server sends everything after it, and any edits the client made offline are sent as pending operations and transformed or merged. Long offline sessions are where OT is harder and CRDTs fit more naturally.
Observability tracks edit-to-screen latency, reconnect rate and owner changes. Divergence checks compare client and server document hashes, because a transformation bug is silent until two people see different text.
Sequence diagram
The same walkthrough as a UML sequence diagram, one lane per layer or group (12 components in all), left to right in the order a request reaches them, numbered by step. A loop on a lane is a step that stays inside that group. Solid arrows are synchronous calls, dashed are asynchronous.
Key components
Edgelayer
- Access Service: document permissions, share links
- Realtime Gateway: WebSocket connections, auth, rate limiting
Document Session Planedomain
- Document Session Service: orders, transforms and broadcasts operations
- Session Router: maps each document to one owner process
Document Storagedomain
- Operation Log: append-only accepted operations per document
- Snapshot Store: periodic full document snapshots
- Snapshotter: folds old operations into a snapshot
Clientslayer
- Collaborator Client: another person editing the same document
- Editor Client: applies edits locally, buffers pending operations
Presencedomain
- Presence Service: cursors, selections, who is online
- Presence Store: short-lived presence state with expiry (redis)
Observability
- Observability: op latency, reconnects, divergence checks
Sources
Public writing this explainer draws on. Read these for what the real systems actually do.
Make it yours
Copy this diagram and its walkthrough into your own workspace, then change anything: swap Postgres for DynamoDB, add a cache, rewrite the narration. Free, and it uses no AI credits.
Related walkthroughs
- File sync and storage (Dropbox-style)How a file sync service chunks and hashes files, uploads only missing blocks, orders changes in a journal and keeps every device in step.
- WhatsApp-style chat appHow a chat system holds millions of persistent connections, routes end-to-end encrypted messages, and falls back to push when users are offline.
- Chat application (1:1 and group)How a chat app keeps a WebSocket per online user, orders and stores messages per channel, and lets reconnecting clients catch up from history.
This is a learning explainer based on public engineering writing and general design practice. It is simplified, it is not the actual architecture of any company, and it may be inaccurate. Real systems differ in the details. Browse the library.