Download all docs

Recipe: Realtime Collaborative Canvas

This recipe powers a shared diagram that several people edit at once. A websocket carries live edits between clients, a diagram holds the canonical canvas as Mermaid, and a graph stores the node-and-edge structure for queries the picture alone cannot answer. Everyone sees the same canvas update in real time.

The problem it solves

Collaborative editing is hard precisely because it is real-time: every participant must see every change immediately, and the shared artifact must stay coherent under concurrent edits. Polling is laggy and a plain document has no notion of “who is connected”. This recipe wires a push channel to a structured canvas so edits propagate the instant they happen, over a real bidirectional connection.

Elements

ElementRole
websocketReal-time bidirectional channel that pushes edits to every connected client.
diagramThe canonical canvas — Mermaid source plus Triform-side node layout.
graphStores the canvas as queryable nodes and edges.

Flow

  1. Create a websocket element as the live channel. Clients connect and it accepts them; see who is currently editing with connections (returns each connection_id and when it connected).
  2. Push edits to everyone. When one participant changes the canvas, broadcast the change to all connected clients (or a specific room), or send to one connection. This is the real-time propagation.
  3. Hold the canonical canvas in a diagram. Its spec.mermaid is the portable source of truth and spec.layout carries the Triform-side node positions; the workbench renders it as a native canvas. Apply each broadcast edit to the diagram’s source so the canonical state stays current.
  4. Keep the structure queryable in a graph. Mirror canvas nodes with add-node and connections with add-edge, so you can answer structural questions — traverse from a node, shortest-path between two — that the rendered picture cannot.
  5. Close the loop: a client edit → broadcast over the websocket → applied to the diagram source and the graph → every other client re-renders.

What this shows

The websocket element makes real-time a first-class connector — accept, send, broadcast, and connections are the whole vocabulary of a live multi-client channel, with no separate realtime service to run. The canvas itself splits cleanly into two representations: a diagram for the human-facing Mermaid picture and a graph for the machine-queryable structure, each good at what the other is not. Concurrent collaboration becomes “broadcast the edit, update the canonical state” — a pattern, not a platform you have to build.

Next pages