Collaborative Document Engine

Project roadmap

1. 01

   Design the operations

   ~2.5h

   Write DESIGN.md: a document is an ordered list of blocks (id, type and content), and operations are insertBlock (after a block id), deleteBlock, moveBlock, updateBlock (replacing text, or inserting and deleting characters at positions) and setType. Each operation has a client id, a sequence number and the document version it was based on. Explain how the server orders operations and how an operation based on an older version is transformed against the ones that came after it, with examples of conflicting edits. Done when: DESIGN.md covers every operation and conflict case.

2. 02

   Validate operations with Zod

   ~1.5h

   Write Zod schemas for every operation as a discriminated union, with limits (block content length, number of blocks and valid block types), and derive the TypeScript types. Write a pure apply(document, operation) function that rejects operations referring to blocks that don't exist. Done when: tests show valid operations applied and invalid ones rejected with clear errors.

3. 03

   Transform concurrent operations

   ~3h

   Write transform(a, b) that adjusts operation a so it still makes sense after b was applied: character positions shift after inserts and deletes before them, updates to a deleted block are dropped, and moves and inserts relative to a deleted block fall back to a sensible position. The server transforms each incoming operation against every operation since its base version before applying it. Done when: tests with pairs of conflicting operations give the same final document in either order.

4. 04

   Broadcast over WebSockets

   ~2h

   Build a Node.js server with the ws package: clients join a document and receive its current state and version; each operation is validated, transformed, applied, given the next version, acknowledged to its sender and broadcast to the others. Process each document's operations one at a time (with a queue per document) so ordering is strict. Ignore repeated operations by client id and sequence number. Done when: several clients editing the same document stay in sync.

5. 05

   Persist operations and snapshots

   ~2h

   Append every accepted operation to a log (in SQLite or PostgreSQL) before broadcasting it, and save a snapshot of the document every N operations. On startup, or when a document is opened, load the latest snapshot and replay the operations after it. Let clients that reconnect ask for the operations after their last version. Done when: restarting the server loses no accepted operation, and clients catch up after reconnecting.

6. 06

   Build a small React client

   ~2h

   Build a React client that renders blocks, lets you add, edit, move and delete them, sends operations optimistically, transforms its pending operations against incoming ones (the same logic as the server), and shows who's connected. Done when: two browser windows can edit the same document at once and always end up identical.

7. 07

   Test convergence

   ~2.5h

   Write a randomized test that simulates several clients making random operations with random delays and reconnections against the real server, and checks that all clients and the stored document end up identical. Add tests for snapshots and recovery, limits, and invalid operations. Done when: the randomized test passes over thousands of runs.

Resources

• ArticleOperational transformation (Wikipedia)
• DocsZod: discriminated unions
• Docsws: Node.js WebSocket library
• ArticleFigma: how multiplayer technology works
• DocsReact: quick start