Skip to content
Glyph docs

The three document modes

Public

A Glyph document is exactly one of three modes, set when the document is created and stored in meta.mode. The mode controls which surfaces are present and which actions the canvas exposes — everything else (CRDT model, persistence, permissions) is identical.

The three

Section titled “The three”

Whiteboard. Freehand canvas. Frames, sticky notes, shapes, draw strokes, images, threaded comments. No executable graph. Use this for collaborative thinking, design reviews, brainstorming, retrospectives.

Frame

Group + crop region

StickyNote

Inline text on a tinted card

Shape

Rect / circle / diamond

TextBlock

Standalone rich text

ConnectorLine

Free-floating arrow

ImageElement

Bitmap from MinIO

Checklist

Inline TODO list

VoteDot

Click-to-vote affordance

Flow. Executable node graph. Operators connected by typed edges; you press Run and the backend compiles the graph and executes it. Use this for AI workflows, ETL chains, scheduled jobs, webhook handlers.

Hybrid. Both surfaces in one document. The graph runs alongside the freehand canvas; you can pin notes next to nodes, draw arrows that explain a branch, comment on a frame. Use this for documenting a flow inline, for prototyping where the diagram becomes the implementation, or for runbooks where the script is right there.

What stays the same across modes

Section titled “What stays the same across modes”

All three modes share one document model: four Yjs subdocs (meta, graph, draw, comments) with independent broadcast and undo stacks. The mode just changes which subdocs receive substantive content; whiteboard mode leaves graph empty, flow mode leaves draw mostly empty, hybrid uses both.

meta title, mode, owner, created_at, updated_at, settings graph nodes, edges, ports, params, layout draw strokes, shapes, frames, sticky notes, images comments threads, replies, mentions, reactions One Y.Doc per subdoc. Independent CRDTs, independent undo stacks, independent broadcast channels. Provider in web/src/crdt/provider.ts.
Splitting the document into four CRDTs lets the drawing layer stream updates without thrashing the executable graph, lets comments author offline without conflicting with edits, and gives each surface its own undo/redo. Wiring lives in web/src/crdt/subdocs.ts.

Why three and not one

Section titled “Why three and not one”

A pure whiteboard would not let you ship work; a pure flow editor would not let you sketch. Hybrid alone would be the natural choice — but the canvas affordances differ enough between “drawing tool” and “graph editor” that mode-switching the toolbars and shortcuts is a real ergonomic win. The implementation cost of three modes vs one is small (a mode field in meta + toolbar branching); the UX cost of forcing every user into hybrid is large.

Migrating between modes

Section titled “Migrating between modes”

A whiteboard can be promoted to hybrid by enabling the graph surface; nothing is lost. A flow can be promoted to hybrid likewise. Going back — hybrid → flow, dropping the draw layer — keeps the strokes in draw but hides the surface, so a future re-promotion restores them. Modes are a UI choice, not a destructive transformation.