36 lines
2.5 KiB
Markdown
36 lines
2.5 KiB
Markdown
How to draw a box diagram (architecture, components, data flow) that byre's app renders in the transcript, with zoom and highlighting.
|
|
|
|
# Box diagrams
|
|
|
|
A fenced block with the language `diagram` draws boxes in rows with arrows between them. The app lays it out itself, so you never place coordinates. Clicking it opens a full-size view: pinch or scroll to zoom and pan; clicking a box highlights it, its arrows and its neighbors; each `highlight` line becomes a button there. It is the only diagram format byre draws; a ```` ```mermaid ```` block shows as plain code.
|
|
|
|
```diagram
|
|
row
|
|
app "Byre.app" "REST + SSE · WebSockets"
|
|
row
|
|
server "internal/server" "REST · SSE · WebSockets" blue
|
|
aside store "internal/store" "byre.db, SQLite WAL" green
|
|
row
|
|
manager "agents.Manager" amber
|
|
coord "coordinator" "level-triggered"
|
|
live "live sessions" "turn end: commit, snapshot"
|
|
app -> server
|
|
server -> manager "start · message"
|
|
manager -> store "writes"
|
|
store ..> server "events → SSE"
|
|
store ..> coord "poke"
|
|
highlight "Event loop" store server coord
|
|
```
|
|
|
|
- `row` starts a row; rows stack top to bottom. The boxes indented under it sit side by side, stretched to a common width.
|
|
- A box is `id "Title" "detail line" ...`, then optionally a color: `blue`, `green`, `amber`, `red` or `plain` (the default). The id is letters, digits, `_` and `-`, unique in the diagram. Without a title the id is shown.
|
|
- A box indented under another box is its child; children sit side by side inside their parent, and nest to any depth.
|
|
- `aside` before a top-level box puts it in a column to the right of the rows, level with its row. Use it for shared state (a database, git) that many rows touch.
|
|
- `a -> b "label"` draws a solid arrow and `a ..> b "label"` a dashed one; the label is optional. Arrows route around boxes, and may end on a child or a parent.
|
|
- `highlight "Name" id id ...` names a set of boxes to light up together, with the arrows between them.
|
|
- Lines starting with `#` are comments. A mistake shows the source with the reason it wasn't drawn.
|
|
|
|
Keep each box to a title and one or two short detail lines, and draw only the arrows the reader needs; a picture with every dependency in it reads worse than prose.
|
|
|
|
Check a diagram before you send it: `render_diagram` takes the block's body and returns a PNG of what the app draws, or the reason it can't. Look for crossing or overlapping arrows and labels sitting on top of each other, and adjust the rows, `aside` or arrows until it reads cleanly.
|