Archify: Verifiable Interactive Diagrams from Coding Agents

Turning "explain it clearly" into an auditable process

Archify is an agent skill. Give it a plain-language description, a question, or a pasted Mermaid diagram, and it produces not an image but a self-contained interactive HTML file: openable locally, shareable with a colleague, explorable in the browser, and exportable to PNG, JPEG, WebP, SVG or WebM. The repo's positioning is deliberately narrow: it is neither a general-purpose drawing editor nor a Mermaid skin, but a generation-and-acceptance pipeline that turns technical intent into a communication artifact. The default output is a single HTML file; the editable source is typed JSON, and both are meant to be built upon.

Installation is one command, npx skills add tt-a1i/archify -g, with official support for Cursor, Claude Code, Codex CLI and OpenCode. The license is MIT; the version at ingest time was v3.0.1 (2026-09-28), and the code lineage traces back to Cocoon-AI/architecture-diagram-generator (MIT v1.0). Community signals include #1 on GitHub Trending's weekly all-language list (screenshot published by the creator on 2026-09-01), a QbitAI feature plus developer interview, and public shares from developers such as midudev.

Five diagram types, one typed JSON IR

Archify converges "diagram" into five semantic types, each with its own JSON schema and showcase example: architecture (components, services, storage, boundaries), workflow (CI/CD, approvals, tool calls, runbooks), sequence (call chains, cache fallback, auth, async traces), dataflow (pipelines, lineage, sensitivity boundaries), and lifecycle (states, retries, waits, terminal outcomes). When the right type is unclear, the repo ships a zero-dependency CLI as the referee:

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json

Mermaid is treated as input, not as a template: flowchart reads as workflow (or architecture for a component map), sequenceDiagram as sequence, stateDiagram as lifecycle. Topology and meaning are read; Mermaid styling is not mechanically carried over. Layout judgment is deliberately left to the agent: hierarchy, spacing, routes and emphasis are model decisions, while shared automatic endpoints spread deterministically instead of piling arrows on one midpoint. Every request gets its own folder, .archify/<type>-<slug>-<timestamp>/, holding candidate.json and the output HTML; repair reruns reuse the same folder so earlier versions stay intact.

finalize: four gates, one receipt, non-zero is never success

The whole delivery chain collapses into a single command. finalize runs showcase validation, delivery rendering, a strict provenance check and a real-browser check in order, stopping at the first gate that fails; a non-zero exit is never success, and SKILL.md states this as a hard rule. A passing run emits a compact receipt: stable rule codes, the exact failing subject, measured evidence, and only supported repair controls. The agent gets neither a Node stack trace nor a vague "try again". Repairs are capped at two rounds; beyond that the semantics need rethinking, not another nudge.

flowchart LR
    A["candidate.json"] --> B["validate: schema + layout rules"]
    B --> C["deliver: render candidate in place"]
    C --> D["check: strict provenance"]
    D --> E["browser-check: real browser"]
    E --> F["receipt: rule codes + subject + evidence + fixes"]
    B -->|non-zero| G["stop; no atomic replace"]
    E -->|pass| H["atomically replace target HTML"]

Only a passing candidate atomically replaces the target file, so the last verified diagram can never be overwritten by a half-baked one. The optional preview mode is loopback-only: it watches a single JSON file on a random 127.0.0.1 port, reloads only after the newest candidate passes every gate, and keeps the last-good artifact visible when a save is incomplete or invalid. Failure receipts expose diagnostics[], and repairs may only apply each subject's supportedFixes; visual review is reported separately and never merged into the automated gates.

Truth first: interactions reuse only authored topology

Every "smart" viewer feature obeys the same discipline: focus, upstream/downstream reach, exact routes, role lenses and stories all reuse authored nodes and relationships. They never invent topology and never claim runtime impact. Architecture's optional deployment-ownership profile fails closed: if the author omits owners, region placement, private database scope or named crossings, validation fails outright. Nothing is inferred implicitly, and live infrastructure is never inspected. Share cards name their scope the same way: Route Share Cards and Reach Share Cards are 1200x630 and retain the full diagram as context, so one traced path can never pose as the whole architecture.

The viewer is a keyboard-driven exploration surface: ? opens the factual diagram guide, / finds a semantic node, R traces a directed route, L compares roles, M opens the overview radar, F enters presentation stage, S cycles visual styles, T toggles the theme, E opens export. Stable deep links restore #focus=, #reach=upstream|downstream, #route=a~b and #lens=, so a shared link reopens the exact same reading. Motion is opt-in, finite, respects prefers-reduced-motion, and never enters canonical exports. meta.locale ships en and zh-CN built in; other languages supply meta.translations (canonical message key to translated string), and a missing translation falls back to English with disclosure.

Source evidence and Architecture Delta

When a diagram must reflect real code, Archify demands evidence rather than impressions. Evidence-backed Architecture nodes mark themselves SRC n and open Git-verified files and line ranges pinned to one public commit, so readers can check the claim and see how old it is. Ordinary artifacts stay source-free instead of wearing "I read the code" as default decoration.

For design and PR review there is Architecture Delta: node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json renders validated Before / Delta / After snapshots side by side with a machine receipt. You can select an authored change or play one finite, viewer-only Review. It explicitly infers no impact, risk or merge safety; the comparison states only the added, removed, changed and moved authored facts.

Self-benchmarks: an ordinary-model floor, and the repair-round ledger

The repo ships two benchmarks, both conservatively scoped. ordinary-model-floor measures first-pass usability for ordinary models: the pi agent ran 3 models across 5 cases for 15 attempt-1 candidates, pinned to commit 66414c7 and one packaged skill SHA-256. The calibrated verifier reports 10/15 first-pass usable, with five deterministic visual-quality failures and zero semantic or operational failures. The more honest paragraph follows: under the current stricter verifier, both the original and the post-fix matrices score 8/15 (MiniMax 4/5, DeepSeek 2/5, Qwen 2/5), and the README states plainly that a single sample does not demonstrate an overall uplift.

repair-rounds measures the cost inside the feedback loop: eight deterministic defect classes (meta-missing-output, node-invalid-type, node-long-label, node-duplicate-id, edge-dangling-target, viewbox-oversized, title-overflow, subtitle-overflow) are injected into checked-in fixtures, and the harness records rounds to pass, first-round disclosure rate, first-detection stage, late-discovery rate and actionability. The two header-overflow classes use unbreakable strings so they can only be measured by real browser layout, which is exactly why the browser-check gate exists. The public Proof Lab holds all 11 checked-in scenarios with their JSON sources and validation receipts for line-by-line review.

Getting started, and the boundaries

Environments without shell access still have a fallback: hand-place architecture SVG into assets/template.html, use CSS semantic classes rather than inline colors, and follow the visual review contract. Update awareness is folded into the finalize receipt (a bounded manifest GET, disable-able via ARCHIFY_UPDATE_CHECK_DISABLED=1), and the skill is explicitly forbidden from installing or updating anything on its own initiative. A reminder is information, not an action.

The boundaries are equally explicit: static output is the default and motion must be requested; visual review is optional evidence, and claiming it without doing it is a contract violation; Archify does not replace free-form drawing tools or beautify Mermaid. For engineering teams that need to explain architecture, workflows or sequences to a team or a review board, this generate-validate-browser-verify-receipt pipeline is closer to a deliverable than another screenshot that goes stale.