mufassall

Cheat sheet · Case studies

Case: Figma multiplayer editing

14 min · Advanced · mufassall.dtwin.uz/en/l/case-figma-multiplayer/

← Open the lesson

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
Final scene
20%

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_bob

Mermaid: 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 online

D2

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
@enduml

PlantUML: 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
@enduml

Recap

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

MetricStartEnd
Unacknowledged00
Flickers00
Lost edits00

Steps

  1. Case One process per document, changes over a WebSocket

    Clients are web pages that talk to a cluster of servers over WebSockets.

  2. 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.

  3. Case Different properties never conflict

    Alice changes the fill of a rectangle while Bob moves it.

  4. Case Same property: the last value the server got wins

    Now both edit the same text property at the same time.

  5. Problem A stale echo makes the screen flicker

    A client applies its own change at once, without waiting for the server.

  6. 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.

  7. Fix Clients make object ids themselves

    Creating and deleting objects are explicit actions; writing to an unknown id does not create anything.

  8. 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.

  9. Fix Ordering children with fractional indexes

    The order of layers inside a parent is a fraction between 0 and 1.

  10. Problem Editing while offline

    Bob's laptop loses the network.

  11. 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.

  12. Recap Recap

    What to take from Figma's design.