Knowledge Islands Enter Arcadia
Menu

← Docs · Standards

Diagrams

You can keep a diagram useful after the first presentation by recording the question it answers, the evidence behind it and the exact source needed to regenerate its figure and interactive view when that evidence changes.

Source, build, export, receipt and freshness A workflow diagram generated by Archify. 01 / Evidence and rendering 02 / Committed forms and review Read evidence · One question, audience and revision · Evidence and rendering Read evidence One question, audience and revision JSON source · Cite the supporting files and lines · Evidence and rendering JSON source Cite the supporting files and lines Build viewer · Pass all four showcase gates · Evidence and rendering Build viewer Pass all four showcase gates Export SVG · Canonical self-contained ki form · Committed forms and review Export SVG Canonical self-contained ki form Check receipt · Source and viewer bytes match · Committed forms and review Check receipt Source and viewer bytes match Review freshness · Compare changes; set last_checked · Committed forms and review Review freshness Compare changes; set last_checked matches Legend Agent logic Policy Context / trace
Review the traced evidence, update the JSON source, build the viewer, export its SVG and check the receipt and freshness before committing the set. Interactive

What it is

A living diagram is a maintained explanation of one question for one audience. It is authored with Archify from JSON and kept beside a manifest that says what would make it stale. Readers can inspect a portable SVG and, where the repository publishes one, an interactive HTML viewer with search, focus and zoom.

The standard uses five diagram types. Choose by the question:

  • Architecture - What parts connect or depend on each other?
  • Workflow - What steps does a process take, including stops and forks?
  • Sequence - What happens in order between participants for one request?
  • Dataflow - Where does data come from, change and go?
  • Lifecycle - What states does one thing move through, and on which events?

A tree-shaped repository or capability map is drawn as architecture. If an explanation needs two types, split it into two questions and draw two figures.

How it works

The maintained set lives in docs/diagrams/. Each lower-case kebab-case slug has a JSON source named <slug>.<type>.json and a self-contained <slug>.svg. A diagram declaring commit_html = true also commits <slug>.html and <slug>.receipt.json. Otherwise its viewer remains a local build artefact.

The source records its reviewed repository revision and cites the files and lines supporting the drawing. A model or process diagram cites the notes it draws from instead. The manifest, diagrams.toml, has one table per slug with the type, question, audience, traced paths, stale_when, regeneration instructions and last_checked commit. It also selects the SVG form and whether to commit HTML. The README asks each diagram's question and embeds its SVG, linked to the viewer where one is committed.

The four SVG forms serve different readers:

dual      Viewer themes
light     Static light palette
ki        Knowledge Islands day palette
ki-night  Knowledge Islands night palette

The two KI forms use the corresponding Knowledge Islands palette. Static forms resolve their paint values so they remain self-contained. This website uses ki figures on a parchment panel and keeps the viewer's dual theme for exploration.

The receipt fingerprints the committed source and HTML, including their hashes and byte counts, and identifies the renderer. It proves which source produced those viewer bytes. It is generated by the build, never edited by hand. That proof is separate from freshness: unchanged source can still describe a model that has changed.

How you use it

Ivo wants a diagram explaining how the fictional Tern Holm island reviews a survey. He writes one audience and question, selects Workflow, then adds the manifest entry and README section before drawing the source. He reads the governing procedure, freezes its revision and attaches source citations to the relevant steps.

He finalises the JSON through Archify's showcase gates: validation, delivery, artifact checking and browser checking. He exports the canonical SVG in the manifest's chosen form. Where HTML is committed, the build writes the viewer and matching receipt together. On this website, the documented local command is:

bun run --cwd apps/site diagrams:build -- --svg diagram-regeneration

Replace the final slug with the diagram being built. A page embeds the figure as SVG with a caption and a link onward to its interactive view; a screenshot loses the source and scalable figure. Here the figure shortcode supplies that embedding and its Interactive link.

When a traced file changes, Ivo compares the change with stale_when. A relevant change means re-reading the evidence, editing the JSON, rebuilding and exporting the SVG again. An irrelevant change needs review and an advanced last_checked, rather than a needless redraw. He commits the source, forms, receipt and manifest as one maintained set.

What it provides

You get an explanation that can be reviewed, explored and rebuilt without depending on a hosted drawing service. The manifest gives every figure a declared purpose and maintenance trigger. Receipts catch source-to-viewer drift; freshness checks identify evidence changes that need human review.

Boundaries

A matching receipt does not prove the facts in the diagram, and a freshness warning does not prove that a redraw is necessary. Both require judgement. Committed sources, SVGs and HTML must carry no local absolute paths, file URLs, email addresses, private repository names or real people. Use repository-relative citations and fictional worked examples. Auditing committed forms needs neither Archify nor a browser; authoring and regeneration require both, and a failed gate does not produce a verified diagram.