Loading…

Understanding the problem

A collaborative editor lets several people type in one document at once. Each sees their own typing instantly and everyone else's a moment later, with cursors, comments, sharing and version history. The hard part is concurrency: two people change the same sentence at the same moment, both changes must survive, and every screen must end up identical. This page designs the family's one variant, Document editor.

The practice brief states the requirements up front; confirm them in the first few minutes. The core is the path from one keystroke to the same text on every screen.

Functional requirements

CoreCreate a document and share it with people or by link, as viewer, commenter or editor.
CoreSeveral people edit the same document at once: each sees their own typing instantly and everyone else's within a fraction of a second.
CoreSee who else is in the document and where their cursors are.
CoreComment on a passage of text.
CoreSee a document's version history and restore an earlier version.
CoreKeep editing through a lost connection, for up to about a day, and have the edits merged on reconnect.
Below the lineImages, tables and drawings (treat them as objects inside the text).
Below the lineSuggestion mode.
Below the lineSpreadsheets and slides.
Below the lineSearch across documents.
Below the lineExport to other formats.
Below the lineLive cursors that survive a reload.Cursors are live and disposable; nobody needs an old one.
Below the lineEditing inside a spreadsheet or drawing.Embedded objects are treated as single items inside the text.

Non-functional requirements

ConsistencyNo edit is lost: when two people change the same passage at the same moment, both changes survive, and everyone ends up with exactly the same text.
LatencyYour own typing shows at once, and other people's edits appear within about 200 ms at p99.
DurabilityAn edit the editor has shown as saved survives any server crash.
LatencyAny document, however old, opens in about a second.
SecurityRemoving someone's access takes effect at once, even if they have the document open.
AvailabilityEditing keeps working when a server, or a whole region, fails.

Scale

From the briefNumbers here are given in the practice brief.

ScaleAbout 50 million daily users and about 1 billion documents.
ScaleAbout 2 million documents open for editing at peak, over about 5 million live connections.
ScaleAbout 300,000 edits a second at peak (typing, deleting, formatting).
ScaleMost documents have 1–3 editors at once; a busy document can have about 5,000 readers and about 100 editors.
ScaleDocuments run up to a few hundred pages; version history is kept for their whole life.

Out of scope

Out of scopeSign-in and accounts.
Out of scopeBilling.
Out of scopeSpell-check, grammar and AI writing features.

Check yourself

Why is last-save-wins the one answer that fails outright?
Show answerHide answer
Two people's saves start from the same text, so the later one erases the other's words without anyone noticing, which breaks the first requirement.

The numbers that shape the editor

Illustrative exampleNumbers here are illustrative: round figures to reason with, not measurements.

Work out only the numbers this design depends on, and say what you assume about people per document, bytes per edit and connections per server.

Back of the envelope for the document editor

Quantity	Value	Working
Edit messages sent	About 600,000 a second	300,000 edits a second, each to about two others.
Servers for connections	About 100	5 million connections at about 50,000 a server.
Edits stored	Under 1 TB a day	About a third of peak on average, about 100 bytes an edit.
Memory for open documents	About 400 GB	2 million open documents at about 200 KB each.
One busy document	About a million messages a second	100 editors at about 2 edits a second each, each edit sent to about 5,100 people.

What the numbers tell you

Edits are tiny; the live connections and the fan-out are what the servers carry.
One busy document, sent to everyone, would outgrow any one server.

Read:Learn: Numbers and capacity estimation

Try it: The numbers that shape the editorGuided practice · Collaborative document editor, Document editor · Senior

Check yourself

Which number tells you readers of a busy document need their own path?
Show answerHide answer
The busy document's fan-out: every edit sent to thousands of people from one server is about a million messages a second, far more than the edits themselves.

Core entities

Start from the reads: may this person open this document, and as what; list my documents; open a document; show its comments. A document's text is not a column: it is the edit log plus snapshots, designed in the deep dives.

The records that matter

Record	Key fields	Why it exists
Document	`doc_id`, owner, title	One row per document.
Member	`doc_id` + `user_id`, role	A role check is one lookup.
User document	`user_id` + `doc_id`, role	A person's list, one lookup.
Link share	`doc_id`, token, role, enabled	Sharing by link, turned off at will.
Comment	`doc_id` + `comment_id`, passage, author, body, resolved	Kept beside the text, attached to a passage.
Edit	`doc_id` + revision, change, `client_edit_id`	The log that is the document.

Where each kind of data lives

Data	Store	Why
Documents, sharing, comments	PostgreSQL or Spanner, split by document id	Small, related, and a sharing change must be exact.
Edit log	A replicated store keyed by document and revision, such as Cassandra	Written at typing speed, read in order.
Snapshots	Object storage such as S3	Large, written now and then, read on open.

Architecture diagramSmall records in SQL, the text as a log and snapshots

Read:Learn: Data model design Learn: Storage choice justification Learn: PostgreSQL Learn: Apache Cassandra

Try it: Documents, sharing and commentsGuided practice · Collaborative document editor, Document editor · Senior

Check yourself

Why keep comments beside the text rather than inside it?
Show answerHide answer
So text edits don’t have to rewrite them and they can be resolved on their own. The comment is attached to its passage, so it moves when text is typed before it.

The API

Plain calls for documents, sharing, versions and comments, and a WebSocket for editing, a two-way connection the editor keeps open (RFC 6455 (opens in a new tab)). Edits are small changes, not the whole document.

The calls and the live connection

Call or message	Request	Response	Errors
`POST /v1/docs`, `GET /v1/docs/{id}`	Title, or nothing	The id, or the document and your role	`401`, `403`, `404`
`POST`, `DELETE /v1/docs/{id}/members`	Person and role	`201`, `204`	`403` unless you may share
`PUT /v1/docs/{id}/link`	Role, or off	The link	`403`
`GET /v1/docs/{id}/versions`, `POST …/restore`	Cursor, or version	Versions, or the new revision	`403`, `404`
`POST /v1/docs/{id}/comments`	Passage and body	`201` and the comment id	`403` unless you may comment, `404`
`WS /v1/docs/{id}/live`: edit	A small change	An acknowledgement	Closed on `403`
`WS`: cursor	Position, a few times a second	Others’ cursors	Not stored

Read:Learn: API contract design Learn: Protocols and real-time transports

Try it: Opening, editing and sharingGuided practice · Collaborative document editor, Document editor · Senior

Check yourself

Why not save edits with a PUT of the whole document?
Show answerHide answer
It grows with the document, arrives too slowly for others to see typing live, and two saves from the same text overwrite each other.

High-level design

Build the design one flow at a time; the deep dives then harden the parts an interviewer pushes on.

Ana types, Ben sees it

Every editor of a document ends up connected to the one server that holds it, so each edit passes through one place.

Ana's editor shows her word at once and sends the edit over its WebSocket to a gateway.
The gateway forwards it to the document's server, found by document id.
The server saves the edit and acknowledges it to Ana.
It pushes the edit to every other connection on the document; Ben's editor applies it.

Architecture diagramAna types, Ben sees it

Both editors are joined to the one server that holds the document; it saves each edit, acknowledges it and pushes it to everyone else.

Diagram as text

Components: Ana's editor (Client); Gateway (API gateway); Document server (Service); Edit log (NoSQL DB); Ben's editor (Client); Gateway (API gateway). Connections: Ana's editor → Gateway (1. edit (shown at once)); Gateway → Document server (2. by document id); Document server → Edit log (3. save); Document server → Gateway (4. push to the others); Gateway → Ben's editor (5. apply).

Read:Learn: Real-time delivery architecture Learn: Protocols and real-time transports

Try it: From a keystroke to everyone's screenGuided practice · Collaborative document editor, Document editor · Senior

Keep reading+1 min

Finding the document’s server

A routing table in a consensus store, or consistent hashing on the document id, tells a gateway which server holds a document. Gateways stay stateless, so they can be added freely; document servers move documents between them with a handoff.

Check yourself

Ana and Ben are connected to different gateways. How does her word reach him?
Show answerHide answer

Ben opens the document

Opening checks his role, loads the document fast, and then joins the live stream at the right point.

Ben's editor asks the document API to open the document; it checks his role.
It returns the latest snapshot and the edits after it.
The editor opens its WebSocket, and the gateway joins it to the document server, which sends new edits from there.

Architecture diagramBen opens the document

Design Google Docs

The answer in two minutes

Also asked as

What interviewers look for

The decisions that matter

Understanding the problem

Functional requirements

Non-functional requirements

Scale

Out of scope

The numbers that shape the editor

Core entities

The API

High-level design

Ana types, Ben sees it

Finding the document’s server

Ben opens the document

Sign in with Google to read the rest

Practise this

Cursors and who is here

The answer in two minutes

Also asked as

What interviewers look for

The decisions that matter

01Understanding the problem

Functional requirements

Non-functional requirements

Scale

Out of scope

02The numbers that shape the editor

03Core entities

04The API

05High-level design

Ana types, Ben sees it

Finding the document’s server

Ben opens the document

Sign in with Google to read the rest

12Practise this

Cursors and who is here

Understanding the problem

The numbers that shape the editor

Core entities

The API

High-level design

Practise this