Architecture diagrams
DraftDiagrams on this site are authored as Mermaid source inside the page. This records the conventions and collects diagrams that do not belong to any single subject page.
Why source rather than images
A rendered image cannot be diffed, corrected, searched or restyled. Source can.
| Property | Image | Mermaid source |
|---|---|---|
| Version control | A binary blob; changes are invisible in a diff | Text; changes are reviewable |
| Correction | Requires the original tool and file | Edit the page |
| Theming | Fixed; usually wrong in one of light or dark mode | Rendered to match the reader’s theme |
| Searchable | No | Yes, the labels are text |
| Accessibility | Needs separate alt text | Text is present in the source |
The theming point is practical rather than aesthetic. A diagram exported with a white background is unreadable in dark mode, and this site renders in whichever theme the reader has chosen.
When a diagram earns its place
A diagram that restates the surrounding prose should be deleted. The test is whether it shows something the text cannot say as compactly.
- Good: a decision structure
- Branching logic with several conditions is genuinely hard to follow in prose and clear as a flowchart.
- Good: a loop or feedback path
- Cycles are awkward in linear text and immediate in a diagram.
- Good: a pipeline with branches
- A processing chain where different paths are taken under different conditions.
- Bad: a list drawn as boxes
- If the content is a sequence with no branching, it is a list. Write the list.
- Bad: a diagram of the page structure
- The reader can see the headings.
One diagram per mechanism, not one per page. Several pages on this site have a single diagram because they contain a single mechanism worth drawing, and a page with no branching structure correctly has none.
Conventions
Consistency across pages matters more than any individual choice, so the following are used throughout.
| Element | Convention |
|---|---|
| Direction | flowchart TD for processes and decisions; flowchart LR for pipelines and signal chains |
| Decisions | Curly brace nodes, phrased as questions |
| Edge labels on decisions | yes and no, or a short condition |
| Line breaks in labels | <br/>, to keep nodes narrow and readable |
| Node text | Sentence case, no terminal punctuation |
| Loops | Drawn explicitly rather than implied by prose |
Two syntax cautions apply to this site specifically.
Node labels containing punctuation should be quoted, because unquoted parentheses and some other characters break the parser.
Mermaid blocks are the only fenced blocks permitted in content. The style guide prohibits code in content, and mermaid is diagram source rather than code.
Notation used on this site
The diagrams across the subject sections use a small consistent vocabulary.
| Shape | Meaning |
|---|---|
| Rectangle | A process, state or component |
| Curly braces | A decision or test |
| Labelled edge | A condition or a transition |
| Dashed edge | A constraint or a note about the relationship, not a flow |
Dashed edges are used sparingly, for cases where an arrow would wrongly imply a sequence. The raw-data-preservation constraint in Experiments is drawn this way.
Accessibility
A diagram is not a substitute for the text. Every diagram on this site is surrounded by prose that states the same thing, so that a reader who cannot see the diagram loses nothing essential.
The stronger form of this rule is that if the surrounding prose cannot be written, the diagram is doing work that has not been thought through, and the right response is to think it through rather than to rely on the picture.
Index
Diagrams belonging to a subject live on that page. This section collects diagrams that span sections or that are working sketches not yet attached to anything.
No entries yet.
References
This page is a convention. Mermaid’s own documentation covers the syntax.