README system diagram: research (2026-11-01)
1. Best practices
Section titled “1. Best practices”- Level. The README diagram is a C4 container view: a container is “a runtime boundary around some code that is being executed” (C4 container).
- Notation (C4 notation): a title; a key for notation and acronyms; each element gets a type, a short responsibility and its technology; every line is one-directional, labelled specifically (“not Uses”), and container lines name the protocol; colour consistent, safe for greyscale and colour blindness; the diagram “can stand alone”.
- Colour and alt text. Colour must not be the only cue (WCAG 1.4.1). A complex image needs a short alt text plus a longer description (WAI complex images). Mermaid’s
accTitle/accDescrbecome<title>/<desc>witharia-labelledby/aria-describedby(Mermaid accessibility). - Direction and grouping. Mermaid supports
subgraph … endandLR/TBlayouts, but a subgraph’s owndirectionis ignored once its nodes link outside it (flowchart syntax). Inferred: LR follows the reading order; grouping by deployment boundary (Mac vs Mech) makes the Wi-Fi edge cross it. - Size. C4 gives no box count. Inferred: 5 to 8 boxes, 2 or 3 short lines each.
2. Tools
Section titled “2. Tools”| Tool | Source | GitHub | Site / dark mode | Cost, look |
|---|---|---|---|---|
| Mermaid flowchart | fenced block in the README | native (GitHub diagrams) | Material renders it and follows its colour scheme for flowcharts (Material diagrams). GitHub picks dark or default from the viewer’s mode (its bundle, read below). |
zero CI; generic look |
Mermaid architecture-beta |
same | renders (the bundle has an architecture detector) |
Material does not style it | beta, syntax “may change”; built-in icons are cloud/database/disk/internet/server; custom icons need a registered pack; edge labels undocumented (architecture) |
| Mermaid C4 | same | renders | fixed style | no automatic layout, no legends or tags (C4 syntax) |
| D2 0.9.0 (Sep 2026) | .d2 |
not native | CI renders the SVG (d2 in.d2 out.svg, exports); --dark-theme embeds a dark theme that follows the system preference; --sketch gives a hand-drawn look (themes, sketch) |
one Go binary (install); best-looking text-sourced option |
| Graphviz / PlantUML | .dot / .puml |
not native (GitHub renders only Mermaid, GeoJSON, TopoJSON, ASCII STL) | built in CI | PlantUML needs Java |
| Excalidraw | .excalidraw or SVG with the scene embedded (exportEmbedScene, export utils) |
as an image | one fixed palette | hand-drawn; edited by hand; no reviewable diff |
| draw.io 32.6 | .drawio.svg |
as an image | one fixed palette | hand-edited |
Version drift (verified today). GitHub’s Mermaid viewer bundle calls renderer.draw(…, "12.2.0", …), and its defaults are layout:"elk". Material 9.7.7, the version pinned in uv.lock, loads unpkg.com/mermaid@11/dist/mermaid.min.js, so it gets 11.17.x with dagre. Mermaid 12.0.0 is breaking: “Existing flowcharts … will re-lay out and recolour; add layout: dagre, theme: default and look: classic to keep the old look” (12.0.0 notes). So the README diagram lays out differently on GitHub and on the site unless the block pins layout.
Dark mode for images. GitHub supports <picture> with prefers-color-scheme sources (GitHub quickstart). Inferred: an SVG’s own media query follows the OS setting, not GitHub’s theme setting.
3. Examples
Section titled “3. Examples”- PX4. The architecture page shows a large SVG in two bands: middleware above, flight stack below. Its source is a draw.io file on Google Drive, and a comment warns arrows can come out wrong on export (source). The drift ADR 0009 forbids.
- Reachy Mini desktop app (Pollen Robotics). The README uses a Mermaid
flowchart TBwith subgraphs per runtime (Frontend, Backend, Python Sidecar, External, Hardware). Its edges carry the protocol:IPC,WebSocket 20Hz,WebRTC :8443,Serial/USB. Good edge labels; about 17 boxes, too many for a front page. - Home Assistant. The architecture overview shows a 3-layer stack (OS, Supervisor, Core): one bullet per layer, then one committed SVG with alt text.
4. Recommendation
Section titled “4. Recommendation”- Keep a Mermaid flowchart in the README (recommended). The README is its source, GitHub and the site render it, and it needs no CI or committed output. Add
layout: dagre(orelk) in the frontmatter so the layout is the same on GitHub and the site, plusaccTitle/accDescr,LR, the two groups, protocol edge labels and a one-line key under it. Not a picture of the Mech, so Blender’s rule does not bind it (inferred). - D2 source, with the SVG built in CI and served from the site. It looks better (sketch mode, a dark theme) but adds a binary to CI. The README needs an absolute site URL (the last deploy, not the PR’s version); dark mode follows the OS.
- Excalidraw or draw.io. Hand-made look; manual edits, no text diff.
- Not recommended:
architecture-beta(beta, no edge labels, icons need registration), Mermaid C4 (fixed style, no legend) and Graphviz/PlantUML (no gain over D2).
Sketch (6 boxes, 2 groups):
flowchart LR subgraph Mac CC["Claude Code<br/>hooks"] -- "Unix socket<br/>one line per event" --> NS["noggin service<br/>times each turn, drops Triggers while Busy"] end subgraph Mech C1["Core 1: eyes<br/>ESP32-C3, MicroPython"] --> S1["4 servos<br/>lids, eyes"] C2["Core 2: neck"] --> S2["3 servos<br/>pan, tilt, mouth"] end NS -- "Wi-Fi: UDP + HMAC<br/>USB-C fallback" --> C1 NS -- "Wi-Fi: UDP + HMAC" --> C2Key line: “Arrows show commands; each Core plays a gesture to its end.”
Conflicts in the current diagram (sources: ADR 0003, ADR 0005, GLOSSARY):
- The hooks-to-service edge is unlabelled; ADR 0003 says it is a Unix socket.
- The diagram puts the USB-C fallback on both Core edges, but ADR 0005’s known limits say “the USB fallback assumes the eyes Core” (
USB_CORE). - The diagram says “jaw” and “Turn”; GLOSSARY says “mouth” and “turn”.
5. The check (#256)
Section titled “5. The check (#256)”Verified 2026-11-01 on npm: mermaid latest is 12.2.0, the newest 11 is 11.17.2, and @mermaid-js/mermaid-cli 11.17.1
is the last CLI on Mermaid 11 (backport-v11 tag; it asks for mermaid ^11.14.0). test_site.py runs that CLI with
mermaid@11.17.2 named beside it, so every block renders in headless Chrome with what the site’s mermaid@11 resolves
to today; GitHub’s 12 is checked by eye on the PR.
Since #261 the site no longer floats: mkdocs.yml extra.mermaid pins the version and its sha384, overrides/main.html
loads that script from jsDelivr on pages with a diagram (Material then uses it instead of fetching its own), and
test_site.py takes the CLI’s mermaid@ from the same place and checks the CDN bytes against the hash.
6. Serving it from the site (#265)
Section titled “6. Serving it from the site (#265)”Material 9.7.7’s bundle loads Mermaid only when typeof mermaid == "undefined" (or a stray #mermaid element), from
https://unpkg.com/mermaid@11/dist/mermaid.min.js (read in material/templates/assets/javascripts/bundle.*.min.js); its
diagrams docs show the override, a global window.mermaid defined before the bundle
(Material diagrams). So a site-served script that
fails to load (or fails its integrity) still falls back to that floating CDN copy. A Content-Security-Policy of
script-src 'self' 'unsafe-inline' closes that door: every other script the site ships is its own or inline (Material’s
__md_*), checked on the built pages. Material’s privacy plugin would also self-host external assets, but it fetches
whatever unpkg’s @11 is at build time, with no hash check, so it does not pin.
MkDocs runs hook files named in mkdocs.yml hooks: as plugins, any plugin event without self
(hooks): on_post_build copies the checked file into the site,
so make site, the pages workflow and test_site.py’s build all get it.
mermaid-cli 11.17.1 launches Puppeteer with headless: "shell" (its src/index.js), so only
chrome-headless-shell is needed; Puppeteer 25 skips the full Chrome download when PUPPETEER_CHROME_SKIP_DOWNLOAD is
set (its getConfiguration). npx installs into ~/.npm/_npx/<hash of the package specs>, Puppeteer’s browsers into
~/.cache/puppeteer: those two are what CI caches.
noggin v0.2.26-6-g09bf9b7 · 09bf9b7