Skip to content
noggin

README system diagram: research (2026-11-01)

  • 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/accDescr become <title>/<desc> with aria-labelledby/aria-describedby (Mermaid accessibility).
  • Direction and grouping. Mermaid supports subgraph … end and LR/TB layouts, but a subgraph’s own direction is 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.
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.

  • 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 TB with 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.
  1. 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 (or elk) in the frontmatter so the layout is the same on GitHub and the site, plus accTitle/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).
  2. 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.
  3. Excalidraw or draw.io. Hand-made look; manual edits, no text diff.
  4. 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" --> C2

Key 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”.

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.

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.

byYellow PineYellow Pine

noggin v0.2.26-6-g09bf9b7 · 09bf9b7