Cheat sheet · Case studies
Case: Figma multiplayer editing
The problem
Several people edit one design file at once. How Figma keeps everyone in sync without operational transforms: a server that is the single authority, last-writer-wins per property, hidden echoes, client-made ids, cycle checks and fractional indexing. Source: https://www.figma.com/blog/how-figmas-multiplayer-technology-works/
What you learn
- Why a central authority lets you skip the hard parts of OT and CRDTs
- A document as a map of objects to properties, with conflicts per property
- Why a client hides server changes that conflict with its own unacknowledged ones
- Creating objects offline, rejecting tree cycles and ordering with fractional indexes
- What happens to edits made offline when the connection comes back
Diagram as code
The lesson's final design as text: paste it into Jira, GitLab, GitHub, Notion or your docs, where Mermaid renders by itself. There are D2 and PlantUML (Confluence, IntelliJ) versions too.
Mermaid: flowchart
flowchart LR
n_alice(["Alice's browser"])
n_bob(["Bob's browser"])
n_srv["Document process"]
n_alice --> n_srv
n_srv -.-> n_alice
n_bob --> n_srv
n_srv -.-> n_bobMermaid: request sequence
sequenceDiagram
participant n_alice as Alice's browser
participant n_srv as Document process
participant n_bob as Bob's browser
Note over n_alice,n_srv: One process per document, changes over a WebSocket
n_alice->>n_srv: open a file (simplified)
Note over n_alice,n_srv: A document is a map of objects to properties
n_alice->>n_srv: Alice -#62; server: change
n_srv-->>n_alice: ack: server stored fill of 1:20
Note over n_srv,n_alice: Different properties never conflict
n_srv->>n_alice: server -#62; Alice: Bob's change
Note over n_srv,n_bob: Same property: the last value the server got wins
n_srv->>n_bob: server -#62; everyone: the value it received last
n_bob-->>n_srv: Alice sent AB, Bob sent BC#59; never ABC
Note over n_srv,n_alice: A stale echo makes the screen flicker
n_srv->>n_alice: Alice's screen, fill of 1:20
n_alice-->>n_srv: screen: red -#62; blue -#62; red
Note over n_srv,n_alice: Drop incoming changes that clash with your own pending ones
n_srv->>n_alice: Alice's client: incoming changes
Note over n_bob,n_srv: Clients make object ids themselves
n_bob->>n_srv: Bob -#62; server: create
Note over n_bob,n_srv: Two moves that would make a cycle
n_bob->>n_srv: Bob -#62; server: move frame B into frame A
n_srv-->>n_bob: rejected: Alice already moved 5:3 into 5:2, this would make a cycle
Note over n_alice,n_srv: Ordering children with fractional indexes
n_alice->>n_srv: Alice -#62; server: put 5:9 between two layers
Note over n_bob,n_srv: Editing while offline
n_bob-xn_srv: Bob's laptop is offline
Note over n_bob,n_srv: Reconnect: fresh copy, then replay
n_bob->>n_srv: Bob is back onlineD2
direction: right
n_alice: "Alice's browser" {
shape: rectangle
}
n_bob: "Bob's browser" {
shape: rectangle
}
n_srv: "Document process" {
shape: rectangle
}
n_alice -> n_srv
n_srv -> n_alice {
style.stroke-dash: 3
}
n_bob -> n_srv
n_srv -> n_bob {
style.stroke-dash: 3
}PlantUML: request sequence
@startuml
participant "Alice's browser" as n_alice
participant "Document process" as n_srv
participant "Bob's browser" as n_bob
note over n_alice, n_srv : One process per document, changes over a WebSocket
n_alice -> n_srv : open a file (simplified)
note over n_alice, n_srv : A document is a map of objects to properties
n_alice -> n_srv : Alice -> server: change
n_srv --> n_alice : ack: server stored fill of 1:20
note over n_srv, n_alice : Different properties never conflict
n_srv -> n_alice : server -> Alice: Bob's change
note over n_srv, n_bob : Same property: the last value the server got wins
n_srv -> n_bob : server -> everyone: the value it received last
n_bob --> n_srv : Alice sent AB, Bob sent BC; never ABC
note over n_srv, n_alice : A stale echo makes the screen flicker
n_srv -> n_alice : Alice's screen, fill of 1:20
n_alice --> n_srv : screen: red -> blue -> red
note over n_srv, n_alice : Drop incoming changes that clash with your own pending ones
n_srv -> n_alice : Alice's client: incoming changes
note over n_bob, n_srv : Clients make object ids themselves
n_bob -> n_srv : Bob -> server: create
note over n_bob, n_srv : Two moves that would make a cycle
n_bob -> n_srv : Bob -> server: move frame B into frame A
n_srv --> n_bob : rejected: Alice already moved 5:3 into 5:2, this would make a cycle
note over n_alice, n_srv : Ordering children with fractional indexes
n_alice -> n_srv : Alice -> server: put 5:9 between two layers
note over n_bob, n_srv : Editing while offline
n_bob ->x n_srv : [lost] Bob's laptop is offline
note over n_bob, n_srv : Reconnect: fresh copy, then replay
n_bob -> n_srv : Bob is back online
@endumlPlantUML: components
@startuml
left to right direction
agent "Alice's browser" as n_alice
agent "Bob's browser" as n_bob
component "Document process" as n_srv
n_alice --> n_srv
n_srv ..> n_alice
n_bob --> n_srv
n_srv ..> n_bob
@endumlRecap
What to take from Figma's design.
1) If a server can be the single authority, you can drop much of OT and CRDT complexity. 2) Model the document as objects with properties; conflicts happen only on the same property and resolve last-writer-wins, with atomic values. 3) Apply local changes at once and ignore server changes that clash with your unacknowledged ones. 4) Let clients create ids (client id inside), check tree moves for cycles on the server, and order children with fractional indexes. 5) After offline work, load a fresh copy and replay local edits. And for undo: undoing a lot, copying something and redoing back to the present must leave the document unchanged.
Source: https://www.figma.com/blog/how-figmas-multiplayer-technology-works/
Numbers: at the start and at the end
| Metric | Start | End |
|---|---|---|
| Unacknowledged | 0 | 0 |
| Flickers | 0 | 0 |
| Lost edits | 0 | 0 |
Steps
- Case One process per document, changes over a WebSocket
Clients are web pages that talk to a cluster of servers over WebSockets.
- Case A document is a map of objects to properties
A Figma document is a tree of objects, like the HTML DOM: a root, pages, then what is on each page.
- Case Different properties never conflict
Alice changes the fill of a rectangle while Bob moves it.
- Case Same property: the last value the server got wins
Now both edit the same text property at the same time.
- Problem A stale echo makes the screen flicker
A client applies its own change at once, without waiting for the server.
- Fix Drop incoming changes that clash with your own pending ones
The fix: while a client has an unacknowledged change to a property, it discards incoming server changes to that same property.
- Fix Clients make object ids themselves
Creating and deleting objects are explicit actions; writing to an unknown id does not create anything.
- Problem Two moves that would make a cycle
Each object stores a link to its parent as a property, so moving an object keeps its identity.
- Fix Ordering children with fractional indexes
The order of layers inside a parent is a fraction between 0 and 1.
- Problem Editing while offline
Bob's laptop loses the network.
- Fix Reconnect: fresh copy, then replay
When Bob reconnects, his client downloads a fresh copy of the document, reapplies his offline edits on top of that latest state, and opens a new WebSocket.
- Recap Recap
What to take from Figma's design.