Collaborative Editor — Trade-offs & Decisions

Should live collaboration be built on repeated polling or on persistent sockets?

Problem

The system needs to move edits, acknowledgements, cursors, and heartbeats continuously between clients and the collaboration backend.

Option A — Polling

Clients poll for document updates on a timer and submit edits over short-lived requests. This is simpler to bootstrap, but it adds latency and wastes work when messages are tiny and frequent. Polling is not universally wrong — it is a poor fit specifically for high-frequency interactive collaboration.

Option B — WebSockets (with HTTP and SSE playing supporting roles)

Use a WebSocket Gateway so clients keep one connection open and exchange operations incrementally. HTTP still handles bootstrap and history fetches (loading a document, fetching a snapshot, browsing history). Server-sent events could serve some server→client-only cases, but they do not provide the same single bidirectional channel a collaborative editor needs for both submitting edits and receiving them.

Decision

Why

Real-time collaboration is dominated by small, frequent, bidirectional messages. Persistent connections are a much better architectural fit than repeated polling cycles.

Trade-offs

WebSockets add real operational complexity: backpressure, reconnect handling, connection draining during deploys, and load-balancing long-lived connections. Polling is easier operationally, but the collaboration experience degrades quickly under concurrency.

How should the system guarantee convergence when users edit concurrently?

Problem

Concurrent operations can arrive against stale client views, so the platform needs a reliable reconciliation strategy.

Option A — Operational Transform

Use an authoritative Document Server and Synchronization Engine that transform incoming stale operations against later accepted operations (mechanics in Operational Transform Mechanics).

Option B — CRDT

Represent document state with a CRDT so replicas can merge concurrent operations deterministically (mechanics in CRDT Collaboration Mechanics). This is a legitimate alternative with its own metadata, merge, and compaction trade-offs — not a strictly superior default.

Decision

Why

OT fits naturally when one server shard owns the document timeline and can serialize accepted operations. It keeps the mental model close to "one authoritative order, many replicated clients." This is a design choice for this teaching architecture, not a claim about what any specific production system, including Google Docs, actually runs internally.

Trade-offs

OT concentrates complexity in transform logic, ordered server history, and history retention for reconnect. CRDT does not automatically make offline sync simple or eliminate the need for ordering-adjacent concerns — it shifts complexity into unique identifiers, tombstones, causal metadata, and their garbage collection (see CRDT Metadata & Garbage Collection). Neither approach is universally superior; the choice depends on how centralized ownership and offline behavior are prioritized.

Should one authoritative owner serialize each document's edits, or should multiple writers coordinate on the same document more symmetrically?

Problem

The system must decide where document truth lives while many clients and servers participate in collaboration. "Centralized" is easy to misread here as one server for the whole product — that is not what is being proposed.

Option A — Single authoritative owner per document

Route each document through a Shard Router to one owning Document Server that assigns versions and controls the accepted operation sequence. The server fleet itself is fully distributed and horizontally scaled — only the ordering responsibility for a given document is serialized to one owner at a time, protected by an ownership lease and fencing epoch (see Document Owner Lease & Fencing).

Option B — Multi-writer coordination

Let multiple servers or replicas accept writes for the same document more symmetrically, coordinating through heavier merge or consensus semantics rather than a single serialization point.

Decision

Why

One owner per document simplifies version assignment, transform ordering, and operational debugging while still allowing the platform to scale horizontally by sharding many documents across many servers.

Trade-offs

Single ownership creates hotspots for very popular documents and requires a correct failover and fencing story — without it, ownership transfer risks split-brain (see Document Owner Failover and Document Owner Split-Brain in Failure & Scale Scenarios). Multi-writer coordination can reduce single-owner pressure, but raises reasoning complexity quickly and is not the path this design takes.

Should the editor render a keystroke only after the server confirms it, or apply it locally right away?

Problem

Users expect keystrokes to appear instantly, but the authoritative server still has to validate, order, and durably record edits. This is not simply "choosing weaker consistency" — it is a decision about where local responsiveness and authoritative reconciliation each happen.

Option A — Server-confirmed rendering

Wait for authoritative confirmation before applying edits visibly. This reduces some reconciliation complexity, but typing feel becomes laggy — unacceptable for an interactive editor.

Option B — Optimistic local editing with explicit reconciliation

Apply edits immediately in the Editor Client, then reconcile against the transformed or merged authoritative result once it arrives, backed by an explicit committed acknowledgement (see Operation Durability & Acknowledgements).

Decision

Why

Interactive text editing is extremely latency-sensitive. Users tolerate occasional transformed cursor positions far better than sluggish keystrokes — local responsiveness and authoritative correctness are separate concerns that this design deliberately decouples rather than trades off against each other.

Trade-offs

Optimism requires a robust reconciliation path, an unambiguous acknowledgement boundary, and client logic that can absorb transformed remote state cleanly. Skipping the explicit committed acknowledgement risks a client believing an edit is saved when it is only applied in memory (see Acknowledge Before vs After Durable Commit below).

How much infrastructure should the system spend to make collaboration feel live — and does every kind of collaboration traffic deserve the same freshness budget?

Problem

Real-time collaboration requires persistent connections, fast broadcast, and active server ownership, all of which cost more than slow batch-style saving — but not every message type needs the same freshness guarantee.

Separating freshness classes

Document edits — highest priority, must be delivered and committed correctly. Acknowledgements — high priority, users are watching for confirmation. Presence join/leave — medium priority, tolerates brief delay. Cursors/selections — coalescible, can be sampled or batched without harming the product. History/snapshot maintenance — asynchronous, can lag well behind live edits.

Decision

Why

The core product promise is simultaneous editing. That path deserves the strongest freshness budget, while auxiliary collaboration signals can be bounded, coalesced, or delayed without users noticing.

Trade-offs

Richer real-time behavior across every traffic class raises connection, fan-out, and observability cost. Under-investing in the edit path to save cost makes the product stop feeling truly collaborative; over-investing in presence/cursor freshness spends budget where users won't notice the difference.

Should history be stored mostly as snapshots, mostly as operations, or as a hybrid?

Problem

The system needs efficient bootstrap, restore, and audit behavior without turning every old document open into a full replay job — and without deleting operations that reconnecting or OT-transforming clients still need.

Option A — Snapshot-heavy

Store frequent materialized revisions, each tagged with an exact version boundary, so restores are simple and fast, while retaining fewer raw operations.

Option B — Event-heavy

Store a complete operation log and reconstruct arbitrary revisions by replay. This is faithful, but can be slower for long-lived documents and requires unbounded retention if nothing is ever compacted.

Decision

Why

The hybrid model preserves audit and reconnect detail while keeping document open, resync, and restore costs bounded — as long as the snapshot's version boundary is exact and compaction respects what reconnecting clients and the OT transform path still need (see Snapshot Compaction & Retention).

Trade-offs

Hybrid storage adds compaction and retention policy complexity, but it avoids the extremes of too many bulky snapshots or too much unbounded replay overhead.

Should a client be told an edit is "saved" as soon as the owner accepts it in memory, or only after it is durably recorded?

Problem

There is a real latency cost to waiting for durable persistence before acknowledging, and a real correctness risk to acknowledging before it.

Option A — Acknowledge after in-memory acceptance

Send the ack as soon as the owner validates and applies the operation in memory. Pros: lower latency. Cons: an edit that looks accepted can disappear entirely if the owner crashes before the durable write happens.

Option B — Acknowledge after durable commit

Send the ack only once the operation has been recorded per the configured durability policy (durable log append or replicated write). Pros: a stronger, honest user-visible save guarantee. Cons: additional commit latency before the ack arrives.

Decision

Why

Optimistic local rendering (Decision 04) already gives users an instant-feeling editor. That means the application-level ack is free to represent true durability instead of borrowing speed from an ambiguous "received" signal that can quietly disappear.

Trade-offs

Durable-commit acknowledgement adds latency between an edit and its committed status, and it depends on the durability policy's own write path staying healthy. Weakening this boundary to shave latency reintroduces the risk covered in Persistence Failure After Operation Acceptance (Failure & Scale Scenarios).

Should a document be one synchronization unit, or should large documents be partitioned into independently synchronized blocks?

Problem

Very large or very hot documents can strain a single ownership and ordering stream, but splitting that stream introduces its own complexity.

Option A — Whole-document synchronization

One synchronization stream, one owner, one version sequence per document. Simpler ordering, simpler mental model, but scales only as far as one owner can serialize.

Option B — Block/section/object-level partitioning

Partition synchronization by block, section, or embedded object. Improves scalability for hot sections and very large documents, but complicates cross-block operations, selection ranges that span partitions, and document-wide mutations.

Decision

Why

Document-level ownership is simpler to reason about, easier to fence and fail over, and sufficient for the overwhelming majority of documents. Partitioning is a scaling response, not a default (see Large-Document Partitioning).

Trade-offs

Whole-document sync caps a single document's write throughput at what one owner can serialize. Block-level partitioning raises throughput ceilings but pushes complexity into cross-block operations, formatting spans, and global mutations like find-and-replace.

Should each document have one home-region authoritative owner, or should multiple regions accept writes for the same document?

Problem

Collaborators can be spread across continents, and the system has to decide where authoritative ordering for a document actually happens.

Option A — Home-region authoritative owner

Every document has one authoritative owner in a home region; gateways everywhere terminate client connections locally, but edits route back to the home region for ordering. Simpler ordering and fencing; remote collaborators incur real network latency on their edit round trip.

Option B — Multi-region active writers

Allow multiple regions to accept writes for the same document concurrently. Can lower local write latency for geographically distributed teams, but substantially raises reconciliation and coordination complexity.

Decision

Why

Home-region ownership keeps the fencing and ordering model from Document Owner Lease & Fencing intact without extending it across a wide-area network on every keystroke. Multi-region writers would require synchronous cross-region consensus per operation unless the design accepted a materially different consistency model.

Trade-offs

Home-region ownership means collaborators far from that region feel more latency than same-region collaborators. Multi-region active writers could reduce that latency but at a steep cost in coordination complexity and failure-mode surface area.

Should every cursor movement broadcast to every viewer, or should presence fidelity degrade gracefully at scale?

Problem

Presence is ephemeral and non-authoritative, but it can still become a fan-out bottleneck on documents with large audiences.

Option A — Full-fidelity presence

Broadcast every cursor and selection movement to every subscriber immediately. Feels the most alive on small documents; becomes a fan-out and rendering problem as viewer count grows.

Option B — Coalesced or sampled presence

Rate-limit, coalesce, or sample presence updates, and reduce the number of simultaneously rendered remote cursors for very large audiences.

Decision

Why

Presence is explicitly not document truth (see Presence & Cursor Fan-Out) — it can be stale, sampled, or temporarily unavailable without affecting document correctness, which makes it a safe place to trade fidelity for scale.

Trade-offs

Full fidelity is expensive at large scale and rarely noticed once dozens of cursors are on screen anyway. Aggressive coalescing saves real capacity but should stay proportional — collapsing presence too aggressively on small, normal-sized documents would be a visible regression for no benefit.

How long should accepted operations stay retained before they become eligible for compaction?

Problem

Retention affects the offline reconnect window, OT transformation needs, user-visible version history, storage cost, and snapshot frequency all at once — there is no single universal number that satisfies every one of those pressures.

Option A — Long retention

Keep operation history for a long window. Supports longer offline gaps and deeper user-visible history, but grows storage and can increase snapshot/compaction complexity.

Option B — Aggressive compaction

Compact and discard operation history quickly after each snapshot. Cheaper to store, but forces more reconnecting clients into snapshot-rebase paths instead of normal replay (see Offline Client Returns After History Compaction in Failure & Scale Scenarios).

Decision

Why

Compaction eligibility genuinely depends on multiple independent consumers of the same history (restore, OT transform, offline clients, audit). Treating retention as one global constant ignores that these consumers have different needs.

Trade-offs

Over-retaining costs storage and can slow compaction jobs. Under-retaining pushes more reconnect and OT-reconciliation traffic onto the snapshot-rebase fallback path, which is safe but heavier than a normal incremental replay.

During an uncertain ownership transition, should the system keep accepting writes aggressively, or pause until a fenced owner is confirmed?

Problem

A network partition or coordinator mistake can make it briefly unclear which server actually owns a document. The system has to decide how to behave during that window.

Option A — Continue accepting writes aggressively

Keep serving writes through whichever owner a given client currently reaches, prioritizing availability. Risks two authoritative histories if two servers both believe they own the document (see Document Owner Split-Brain in Failure & Scale Scenarios).

Option B — Briefly pause authoritative writes

Stop accepting authoritative writes for the affected document until a new owner is established with a strictly higher fencing epoch, then resume. Costs a short availability gap for that one document.

Decision

Why

Split-brain document histories are far more expensive to reconcile after the fact than a brief, well-communicated write pause during failover — and the pause only affects the specific document in transition, not the whole platform.

Trade-offs

The pause is a real, user-visible availability cost for the affected document, even if brief. Aggressively favoring availability avoids that visible gap but reintroduces the exact split-brain risk fencing exists to prevent.

Decision summary

The OT and CRDT claims in this page are backed by the papers listed under Further reading at the end of the Architecture Deep Dive.