How to Generate HTML Diagrams from JSON with Archify: Complete CLI Guide

Use archify deliver <type> <input.json> [output.html] to validate, render, and atomically commit a self-contained interactive HTML diagram from any typed JSON specification.

Archify is an open-source CLI tool that transforms structured JSON descriptions of systems into browser-ready HTML diagrams. According to the tt-a1i/archify source code, the tool supports architecture, workflow, sequence, data-flow, and lifecycle diagrams through a three-stage pipeline designed for safety and reproducibility.

Understanding Archify's Three-Stage Pipeline

The rendering process in archify/bin/archify.mjs splits execution into distinct stages:

Stage	Purpose	CLI Command
Render	Produce raw HTML without validation	archify render <type> <input.json> [output.html]
Validate	Run full validation with machine-readable output	archify validate <type> <input.json> --json
Deliver	Safe, atomic workflow with all checks	archify deliver <type> <input.json> [output.html]

The deliver command is the recommended path for production use. It guarantees that generated HTML passes every deterministic check before replacing existing files.

Installation and Setup

Install Archify globally for use across agent environments:

npx skills add tt-a1i/archify -g

The installer places the archify binary under ~/.agents/skills/archify or your platform's equivalent agent skill directory.

Preparing Your JSON Diagram

All diagram types share a common schema located in archify/schemas/. Here's a minimal web application architecture example, matching the shipped example at examples/web-app.architecture.json:

{
  "$schema": "https://raw.githubusercontent.com/tt-a1i/archify/main/archify/schemas/architecture.schema.json",
  "type": "architecture",
  "nodes": [
    { "id": "users", "type": "client", "label": "Users" },
    { "id": "cdn", "type": "cdn", "label": "CDN" },
    { "id": "lb", "type": "load-balancer", "label": "LB" },
    { "id": "api", "type": "service", "label": "API Server" },
    { "id": "db", "type": "database", "label": "Postgres" }
  ],
  "relationships": [
    { "source": "users", "target": "cdn", "label": "HTTPS" },
    { "source": "cdn", "target": "lb", "label": "Edge → LB" },
    { "source": "lb", "target": "api", "label": "Request" },
    { "source": "api", "target": "db", "label": "SQL" }
  ]
}

Save this as web-app.architecture.json. The schema URL enables IDE autocompletion and validation.

Generating HTML Diagrams: Core Commands

Quick Render (Prototyping)

For rapid iteration without validation:

archify render architecture web-app.architecture.json web-app.html

This invokes archify/renderers/architecture/render-architecture.mjs directly and outputs raw HTML.

Production Delivery (Recommended)

For validated, traceable artifacts:

archify deliver architecture web-app.architecture.json web-app.html --json --open

The deliver command executes five sequential operations:

1. Freeze input — creates read-only snapshot specification.snapshot.json in staging
2. Render — runs the type-specific renderer
3. Artifact check — scripts/check-render-output.mjs validates schema, layout, and composition
4. Atomic commit — renderers/shared/output-path.mjs safely moves verified HTML to target
5. Optional open — launches browser when --open is passed

Available Flags

Flag	Values	Effect
--quality	standard | showcase	showcase enables richer presets (signal-flow, blueprint themes)
--repo-root <path>	filesystem path	Enables source-evidence linking for "Evidence" badges
--json	boolean	Outputs diagnostic receipt as JSON
--open	boolean	Opens generated HTML in default browser

Understanding Generated HTML Structure

Archify produces self-contained files with three embedded data blocks:

<script id="archify-data" type="application/json">…JSON source…</script>
<script id="archify-source-evidence-data" type="application/json">…repo evidence…</script>
<script id="archify-receipt-data" type="application/json">…validation receipt…</script>

These enable the viewer (archify/assets/template.html) to:

• Reload and re-render diagrams
• Execute guided story tours
• Trace routes between nodes
• Export PNG and Share-Card images

All functionality works without a server or build step.

Advanced Workflows

Live Preview with Auto-Reload

Start a development server that watches your JSON file:

archify preview architecture web-app.architecture.json

The server binds to 127.0.0.1 on a random port. Changes trigger re-rendering; validation failures preserve the last-good artifact while logging diagnostics.

Delta Comparison

Generate side-by-side before/after diagrams:

archify compare architecture base.json head.json delta.html --json

This produces annotated HTML highlighting added nodes, removed edges, and moved components.

Guided Scenario Generation

Request a pre-built diagram recipe:

archify guide "show a login flow" --json

Returns ready-made scenario specifications for common patterns.

Batch Demo Rendering

Generate the bundled example quickly:

archify demo ./demo-output

Renders examples/web-app.architecture.json to the specified directory.

Production Delivery Example with Full Evidence

archify deliver architecture examples/moca-runtime.architecture.json \
    moca-runtime.html --quality showcase --repo-root $(pwd) --json --open

Internal execution flow:

• Source evidence injection pins the diagram to exact Git commit 9f1a1cf
• Final receipt includes SHA-256 hashes for both specification and artifact
• Composition profile signal-flow confirms visual theme selection

Sample JSON receipt output:

{
  "schemaVersion": 1,
  "ok": true,
  "command": "deliver",
  "type": "architecture",
  "input": "/home/user/moca-runtime.architecture.json",
  "output": "/home/user/moca-runtime.html",
  "specification": { "sha256": "a1b2c3…", "bytes": 1024 },
  "artifact": { "sha256": "d4e5f6…", "bytes": 45872 },
  "validation": {
    "checksPassed": 23,
    "checkCount": 23,
    "compositionProfile": "signal-flow",
    "compositionStatus": "ok"
  },
  "evidence": {
    "verified": true,
    "repository": "https://github.com/mco-org/mco",
    "revision": "9f1a1cf",
    "references": 14
  }
}

Key Source Files Reference

File	Role
archify/bin/archify.mjs	Main CLI dispatcher implementing all commands
archify/renderers/<type>/render-*.mjs	Per-type renderers (e.g., render-architecture.mjs)
archify/scripts/check-render-output.mjs	Final artifact validator run during delivery
archify/renderers/shared/output-path.mjs	Safe atomic file operations
archify/schemas/*.schema.json	JSON Schema contracts for each diagram type
examples/web-app.architecture.json	Reference implementation and quick-start template

Summary

• Install Archify globally via npx skills add tt-a1i/archify -g
• Author JSON diagrams using schema-validated structures in archify/schemas/
• Develop with archify preview for live-reload feedback
• Build with archify render for quick checks or archify deliver for production safety
• Verify outputs contain embedded provenance data for reproducibility
• Extend using archify compare and archify guide for team workflows

Frequently Asked Questions

What diagram types does Archify support?

Archify supports architecture, workflow, sequence, data-flow, and lifecycle diagrams. Each type has a dedicated renderer under archify/renderers/ and matching JSON Schema in archify/schemas/.

Why should I use deliver instead of render?

The deliver command guarantees safety through input freezing, validation, artifact checking, and atomic file replacement. Render skips all checks and overwrites output directly—use it only for rapid prototyping.

How do I enable source code linking in diagrams?

Pass --repo-root $(pwd) to the deliver command. This triggers render-architecture.mjs to inject <script id="archify-source-evidence-data"> containing the exact Git commit, enabling the "Evidence" badge in the rendered HTML.

Can I use Archify without installing it permanently?

Yes. The npx skills add command handles one-time installation. For ephemeral usage, inspect archify/bin/archify.mjs to run the Node.js script directly with node --experimental-vm-modules if dependencies are pre-installed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}