Design document

Design: <system>

Author: <name> · Status: In review · Reviewers: <names>

Context & problem

What exists today, why it's the constraint, and <what waits on fixing it>.

Multiplayer editing routes every keystroke through a central server that transforms operations. It works, but it can't survive offline, and three roadmap items wait on a better foundation.¹

Goals

• <The property the design must have, stated so you could test it>
• Conflict-free merges across web, mobile and offline

Non-goals

• <The adjacent thing reviewers will ask about — name it before they do>
• Rewriting the presence and cursor layer

Requirements

Reviewers tick these in place as they're satisfied.

• <Requirement, phrased as a check someone can run>
• Concurrent edits converge to the same state on every replica
• p95 keystroke-to-render under 16ms²

Proposed design

One paragraph before the diagram. <If the diagram is doing the explaining, the paragraph isn't done.>

A CRDT replica per document on every client, with a durable server replica as the sync hub. Clients exchange compact deltas; the server is a relay and a durability layer, not an authority.

flowchart LR
  Client --> Delta --> Server
  Server --> Broadcast --> Client

Alternatives considered

<Alternative A>

• <Why someone would pick it>
• <Why you didn't>

Keep the central transform, harden it

• No migration, known behaviour
• Offline stays painful and the transform complexity keeps growing

Rollout & migration

1. <Step, with the signal that says it's safe to continue>
2. Dual-write both engines and compare convergence in the shadow path
3. Migrate docs lazily on first open; retire the old engine once parity holds

Open questions

• <The thing you genuinely don't know yet>