System Design: [Collaborative editor name]

Reference design for real-time collaborative document editing: several people edit the same document at once, see each other's cursors, keep working offline and merge cleanly when they reconnect. It compares operational transformation (OT) with conflict-free replicated data types (CRDTs), chooses a sequence CRDT, and specifies the sync protocol, presence, offline merge, persistence with snapshots and compaction, access control and local-first considerations. It follows the structure of the System Design Document template and is pre-filled with a worked design to adapt. Values marked Example are assumptions.

Document control

Approvals

Revision history

Contents

1. Overview
2. Requirements
3. Capacity estimation
4. API design
5. Data model
6. High-level design
7. Detailed design
8. Scalability and performance
9. Reliability, security and operations
10. Trade-offs and alternatives
11. Delivery plan and risks
12. Appendices

1. Overview

1.1 Problem statement

[Example: Our editor saves whole documents with last-write-wins. When two people edit the same document, one person's changes disappear; support receives about 40 "lost work" tickets a week. Users also want to keep writing on trains and planes and sync later.]

1.2 Proposed solution

[Example: Each document is a sequence CRDT stored on every client in local storage. Edits apply locally at once and are encoded as small binary updates. Clients exchange updates through a sync server over WebSocket; the server authenticates, checks permissions, relays updates to other clients editing the same document, and appends them to a durable update log. Periodically the server merges the log into a compacted snapshot. Cursors and selections travel on a separate ephemeral presence channel. Because merges are deterministic on every replica, clients that were offline for days converge with everyone else on reconnect without server-side conflict resolution.]

1.3 Decisions requested from reviewers

2. Requirements

2.1 Functional requirements

2.2 Non-functional requirements

2.3 Out of scope

• [Example: spreadsheets and drawing canvases (other data types later)]
• [Example: comments and suggestions mode (next design, reusing the sync layer)]
• [Example: peer-to-peer sync without a server]
• [Item deferred, with the release that will take it]

3. Capacity estimation

3.1 Assumptions

3.2 Update traffic

Open documents and inbound updates:

Each update is relayed to the other $n - 1$ sessions on average:

Presence adds $C \times p \times (n-1) = 1.5 \times 10^{6}$ small relayed messages per second, never persisted.

3.3 Storage

Update log before compaction, if all inbound updates were kept for one day:

With an average of one third of peak, $U_{in, avg} \approx 170\,000$/s, so about $170\,000 \times 100 \times 86\,400 \approx 1.5$ TB/day before compaction. Compaction (7.6) keeps the steady-state log small.

3.4 Summary

4. API design

4.1 Endpoints and messages

4.2 Message examples

Messages are binary in production; the JSON below shows their fields. The state vector maps each client ID to the number of operations seen from it:

{"type": "sync1", "docId": "d_41K", "stateVector": {"1739201": 1820, "2210988": 455}}

{"type": "sync2", "docId": "d_41K", "update": "<binary: missing operations>", "stateVector": {"1739201": 1820, "2210988": 512, "3301207": 77}}

{"type": "awareness", "clientId": 2210988, "user": {"name": "Linh", "color": "#2f6fdd"}, "cursor": {"anchor": "<relative position>", "head": "<relative position>"}}

4.3 Errors and limits

5. Data model

5.1 Entities

Server-side, a document is a snapshot plus an append-only log of updates since the snapshot. Each client holds the same structure in local storage.

5.2 Storage choices

6. High-level design

All sessions of a document are routed to the same sync node, which holds the document's in-memory room.

7. Detailed design

7.1 OT versus CRDT

The design chooses a sequence CRDT because offline editing (FR-04) and local-first storage are requirements, and because it removes the need for a single ordering server per document.

7.2 Sync protocol (critical path)

Sync is a state-vector exchange followed by incremental updates. The same protocol handles first open, reconnect after a network drop and reconnect after weeks offline.

The client keeps every local update in its local store until the server acknowledges it, so closing the tab before sync never loses work. Relaying happens before or in parallel with the log append so that remote latency is not bounded by disk; the ack that lets the client drop its pending copy is sent only after the append is durable.

7.3 CRDT choice and document model

• Text: a sequence CRDT from the YATA or Fugue family, as implemented by a mature library (for example Yjs, or Automerge for JSON-like documents). Prefer an algorithm that avoids interleaving anomalies when two users insert at the same position concurrently (NFR-05).
• Rich text or structure: a tree of maps and sequences (paragraphs as sequence elements, attributes as maps) bound to the editor's schema through the library's editor binding.
• Markdown sources: keep the Markdown text itself as the replicated sequence, so the source stays canonical and the preview is derived.
• Identity: each client session gets a random client ID (32-bit or wider); operations are identified by (client_id, clock). Reusing a client ID across devices is forbidden because it breaks uniqueness.

7.4 Merge semantics users will see

Undo is scoped to the local user's own operations (an undo manager that only tracks local origins), so pressing undo never removes a collaborator's text.

7.5 Presence and cursors

Cursors are stored as relative positions (anchored to element IDs, not character offsets) so they stay correct while text changes around them. Awareness messages are throttled to 2 per second per client, carry a 30 s timeout, and are never written to the log. When a client disconnects, its presence is removed after the timeout or immediately on a clean close.

7.6 Persistence, snapshots and compaction

• The sync node appends updates in batches (every 20 ms or 64 KB) to the log under (doc_id, seq).
• A document is queued for compaction when its log exceeds Example: 1 000 updates or 1 MB. The worker loads the latest snapshot, applies the log, writes a new snapshot with its state vector, then deletes log entries up to up_to_seq.
• Fine-grained history (who typed what, when) is kept for 30 days through periodic history snapshots; named versions are kept indefinitely.
• Tombstone garbage collection removes deleted content's payload while keeping the IDs needed for merging. Full removal of deleted-element IDs is only safe when no replica can still send operations referencing them, which cannot be known for offline clients; the design therefore keeps the IDs and relies on run-length encoding to keep them small.

7.7 Access control, consistency and local-first considerations

• Consistency model: strong eventual consistency. Any two replicas that have received the same set of updates are identical, regardless of order. There is no global order and no locking; reads are always local.
• Write authorisation: the sync node checks the role on connect and on every update. Updates from viewers are rejected, and the client is told to switch to read-only, keeping its local changes as a private draft rather than discarding them.
• Revocation: removing access stops future sync immediately, but a replica already on the user's device keeps the content it had. State this in the sharing UI; it is a property of every offline-capable editor.
• Server-side deletion of a document deletes snapshots and log; clients receive a tombstone on next connect and remove their replica after confirming with the user that unsynced work exists.
• Local-first: the editor opens and works with no network; the server adds sharing, backup and multi-device sync, but is not required to edit.
• End-to-end encryption (future): the protocol already treats updates as opaque bytes except during compaction. With E2EE, compaction moves to clients, which upload encrypted snapshots.

7.8 Client connection states

Clients expose their sync state in the UI so users know whether their work is on the server.

8. Scalability and performance

Latency budget for a remote edit (target p95 200 ms same region):

9. Reliability, security and operations

9.1 Failure modes

9.2 Security and privacy

9.3 Observability

9.4 Cost estimate

10. Trade-offs and alternatives

11. Delivery plan and risks

11.1 Milestones

11.2 Rollout and rollback

[Example: Convert documents lazily on first open in the new editor, keeping the old representation for 90 days. Rollback exports the CRDT state to the old format, which is lossless for content though not for fine-grained history.]

11.3 Risks

12. Appendices

12.1 Open questions

12.2 Glossary

12.3 References

Standard and licence note

Based on common industry practice and published research on collaborative editing cited in 12.3. This is a reference design to adapt, with illustrative numbers. Original text written for this collection. Template licence: MIT.