Skip to main content

Diagrams

The framework's structure and its delivery path, drawn as diagrams that can be panned, zoomed and followed node by node rather than as pictures of diagrams. Each one lives on the page that explains it; this page is the list.

How a diagram is produced​

Each diagram is authored as a JSON candidate — the source of truth, under docs/blong/draw/archify/ — and rendered to one self-contained HTML file that the docs site serves from its own origin. docs/blong/diagrams.json is the register that says which candidates exist, where each is rendered, and where its poster lives.

The rendered file is a build output and is not committed, so the deploy stages it first:

cd docs/blong
npm run stage-diagrams

The command also captures each diagram's poster in both themes, which is the picture a page shows when the diagram was never staged — so a plain npm run build renders those, and the site builds without the renderer and without the megabytes. It needs the Archify CLI, which is not a dependency of this repository, so point ARCHIFY_BIN at an installed copy:

ARCHIFY_BIN=$HOME/.agents/skills/archify/bin/archify.mjs npm run stage-diagrams

Editing a diagram means editing its candidate and running that command; the rendered file and the posters follow, and a diff of the candidates and the posters is what a review reads.