0001. Archify with typed JSON IR for interactive architecture diagrams

• Status: Accepted
• Date: 2026-09-08
• Deciders: Konrad engagement team
• Needs client validation: No — internal tooling choice, not a Manulife architecture decision
• Domain: tooling

Context

The SOW requires a documented target state architecture and an executive-level presentation of it, delivered over six weeks and revised repeatedly as lines of business are consulted. Two properties matter more than usual here:

1. The diagrams change often. WS 2 runs three weeks of working sessions whose entire purpose is to change the architecture. Diagrams that are expensive to revise get revised less often than the thinking does, and then quietly stop matching it.
2. The diagrams are the deliverable. They go in front of executives and are handed to Manulife at close. They have to look finished, and the reasoning behind them has to survive the handoff.

A drawing tool (Figma, Lucid, Visio, diagrams.net) optimizes for the first draft and taxes every edit after it. Layout is manual, there is no review trail beyond file versions, and the artifact carries no structure a reader can interrogate.

Decision

Author every diagram as typed JSON IR in diagrams/src/ and compile it with Archify, vendored at .claude/skills/archify/.

The renderer is deterministic and validates before it emits: schema, layout, route, and label-clearance checks must all pass, so an artifact that builds is one that reads cleanly. It produces one self-contained HTML file per diagram, statically hostable — Cloudflare Pages when we get there.

Vendored rather than installed globally so that the team and CI render byte-identical output from a pinned version, and so the repository works offline. It doubles as the Claude Code agent skill, which is how the JSON gets authored in practice.

Alternatives considered

Option	Pros	Cons	Why not
Figma / Lucid / Visio	Familiar; precise visual control; client already uses them	Manual layout on every edit; no diff; no review trail; static export	Edit cost is paid three weeks running, exactly when the architecture is most volatile
Mermaid in Markdown	Text-based, diffable, renders in GitHub	Generic auto-layout degrades past ~10 nodes; no interaction; not presentation-grade	Fails the executive-readout bar
Structurizr / C4 DSL	Purpose-built for architecture; multiple views from one model	Heavier model discipline; hosted or Java tooling; house style is fixed	More modelling ceremony than a six-week advisory engagement can absorb
D2 / Graphviz	Text-based, good layout engines	Still generic auto-layout; no interaction layer	Same interaction gap as Mermaid, without the ubiquity

Consequences

Easier. Diagrams are reviewed in pull requests as text. Revisions are cheap, which means they actually track the thinking. Failed layout checks name the exact fix. The output supports route probing, reach tracing, guided views, and presentation mode, so one artifact serves both the working session and the readout. Publishing is a static file copy.

Harder. Precise placement is expressed as coordinates and routes rather than dragged, and the validator is strict enough that fighting a layout is a real cost. The library is pre-1.0 (2.17.0-dev.1) and moves fast — hence the pin.

Committed to. JSON IR is the source of truth; rendered HTML is disposable output. Handoff at close of engagement includes both the sources and the rendered artifacts, plus this ADR so Manulife knows what regenerates them.

Roadmap and cost. None. Internal tooling, no client licence, MIT.

Dependencies and open questions

• Node.js ≥ 18 on any machine that rebuilds diagrams. No other runtime dependency.
• Cloudflare Pages hosting is assumed but not yet set up, and no client-side decision depends on it.
• Manulife's preferred handoff format for deliverables is not yet confirmed (SOW §4 says "preferred format"). If static HTML is unacceptable, PNG and SVG export covers it, and the narrative already lives in Markdown.