COLLAB DASHBOARD

A shared whiteboard is only worth anything if the board outlives the meeting, and this one did not. Server state was a single in-memory Map deleted the moment the last user left; the creator of a board was assigned the viewer role and could not draw on it; presence reported nobody online while the socket was connected; and thirteen of the toolbar's own controls emitted events that no server handler was listening for. It also advertised a sync latency figure that nothing in the repository had ever measured.

Everything durable about a board — strokes, shapes, text, comments, layers — moved into a Yjs document served by Hocuspocus and written to SQLite, which is what makes the board outlive both the people on it and the process serving it. Presence got the opposite treatment: cursors, camera and the stroke currently under someone's pen ride the Awareness protocol, broadcast and never written to disk. Roles moved to the document connection, so a viewer receives a read-only connection and the server rejects its updates whether or not it uses the interface. Then the claims got a harness: browser-level acceptance gates in benchmarks/ drive real Chromium instances against a running stack, and every number on this page is produced by one of them.

Collab Dashboard is a whiteboard two people can open in a browser and draw on together. What makes it worth a case study is not the drawing — it is that the board is a CRDT written to SQLite, so it survives things a whiteboard usually does not: someone editing with the network pulled, two people typing into the same text box, and the server process being killed outright.

It did not start there. An audit that ran the app rather than reading it found the product broken end to end: creating a board made you a viewer on your own board, presence read ONLINE (0) over a connected socket, and all state was an in-memory Map deleted when the last user left — under a boot banner that headlined "Persistence". Forty markdown files described the system, fourteen of them reporting on tests that did not exist.

The rebuild moved everything durable into a Yjs document and everything ephemeral onto Awareness, then went looking for the claims. Thirteen client events had no server handler at all. Seven more bugs surfaced the moment tests existed, including corner detection so inverted that a 48-point rectangle scored 46 corners — which meant hand-drawn rectangles, triangles and diamonds could never be recognised. The last one was found by recording the demo: a zigzag being silently straightened, because straightness was measured locally and a smooth wave is locally straight everywhere.

It is now deployed — a static frontend on Vercel talking to a Node process on Fly in London, because a collaborative session is a long-lived WebSocket and serverless cannot hold one. The deploy immediately produced a bug that nine sprints of local work never could, and it produced an uncomfortable number: 299 ms of sync latency, against 7 ms on a LAN. Taking that number apart is the last thing the project did.

The frontend is React 19 on Vite 7, rendering to a Canvas element. The backend is Express 5 with Socket.io and Hocuspocus, speaking two protocols on one port: a Yjs document surface at /collaboration carrying strokes, shapes, text, comments, layers and embeds, and a socket.io control plane carrying session lifecycle, roles, tool selection and the activity feed. Both are served by one process, because free-tier hosting gives you one.

Durability splits along one line. Everything on the document surface is persisted to SQLite through the Hocuspocus SQLite extension, on a mounted volume — without that mount every deploy would wipe every board, which is written directly above the mount block in fly.toml. Everything on the Awareness channel — cursors, camera, is-drawing, the stroke currently in flight — is broadcast and never written, because presence answers who is here now and persisting it would only restore ghosts.

The document model carries five rules that exist because breaking them fails silently. A stroke is one operation holding an immutable point array, never one per sampled point. Text is the exception and uses Y.Text, updated by diffing rather than clear-and-rewrite, so two people editing one body merge instead of overwriting. Nothing ephemeral goes in the document. Ordering is explicit, because a Y.Map has no meaningful iteration order, so every element carries a sequence number and render order is a sort. And the map key is the id, so element values must not carry their own.

Membership and roles live in SQLite behind the control plane, keyed by a stable client id rather than a socket id — socket ids are minted fresh on every connection, so keying membership by one would mean a reload makes you a stranger and the creator of a board returns to it as a viewer with no way back in. On every document connection the server looks that role up and marks viewer connections read-only. A role change re-evaluates only on a new connection, so the role-updated event carries a flag telling the affected client to reopen its document.

The work started by running the product instead of reading it, and the product did not work. Clicking New Session assigned you the role VIEWER on the board you had just created, so you could not draw on your own whiteboard. Presence read ONLINE (0) while the socket reported connected at a 2 ms ping. Every board was a `const sessions = new Map()` on the server, deleted outright when the last user left — under a boot banner that headlined "Persistence". The repository carried forty markdown files, fourteen of them reports on testing (ten TEST_REPORT_*, four VERIFICATION_REPORT_*), against zero tests. It also carried a "50–80 ms sync" figure with nothing behind it. That audit is committed as RESEARCH-CONTEXT.md rather than summarised after the fact.

The two headline blockers turned out to be one race condition. The client subscribed to socket events only after the server had already broadcast the joined-user message, so the one packet carrying roles and presence arrived before anyone was listening — while the acknowledgement the client did receive already held the correct answer and was being thrown away. Seeding state from the ack removed the race by construction, and that is now pinned by an integration test against a real server over a real socket. Repairing it exposed what was underneath: cursor-move was never emitted by the application at all, so remote cursors could not have worked; the session id was truncated in the one place it was displayed, so nobody could ever join a board; the canvas bitmap was sized from the window rather than its own box, so every stroke landed offset from the pointer, and it measured 1440 px wide inside an 870 px visible area, so you could draw where you could not see. State then moved out of the in-memory Map into a Yjs document persisted to SQLite, and the delete-the-session-when-empty branch went with it. Thirteen client events that had been emitting into the void — layers, templates, smart shapes, text formatting, video embeds — got real handlers on the document, and API.md is now a contract with no documented-but-missing and no emitted-but-unhandled events. Writing the first tests found seven more bugs, the sharpest being corner detection so inverted that a 48-point rectangle scored 46 corners, which meant rectangle, triangle and diamond recognition could never fire on a hand-drawn stroke. Recording the demo found the last one: a hand-drawn zigzag was silently replaced by a straight line, because straightness was measured locally and a smooth wave is locally straight everywhere.

Sync latency is measured as the time from one person committing a finished stroke to that element existing in another browser's document — the CRDT update, the relay, the remote apply and the render — deliberately not a socket ping, because conflating the transport with the product is how the original unbacked number got written down. Thirty samples per environment: 8 ms p50 on loopback, 7 ms p50 / 16 ms p95 over LAN, and 299 ms p50 against the deployment. Almost none of that 299 ms is the application, and the budget was taken apart rather than assumed: the network round trip to the Fly region is ~25 ms, the app's own cost is the 7–8 ms above, and the remaining ~285 ms is free-tier CPU throttling — isolated by showing that GET / does no database work and still costs the same as GET /health, and that over a held-open socket, where the machine cannot be idle, a trivial ping round-trips at p50 322 ms. Persistence was proved by killing the server process, starting a new one, and getting the board back into a browser profile with an empty IndexedDB. The benchmark reports the recovered ink as a pixel count, which is deliberately NOT published here: it is a rasterisation artifact of a synthetic stroke at a fixed viewport, so any change to stroke width or colour moves it, and it did — the figure quoted during the build no longer matches what the same script prints today. What is stable, and what the claim rests on, is that nothing is lost. The permission boundary was driven at the wire with a valid viewer token and no UI involved, plus two forged tokens refused. Remote cursor interpolation was verified as time-based rather than frame-based, converging within 383/375/400 ms at 30/60/144 Hz. Moving the app off localhost was verified across a LAN with only environment variables changed and no source edit.