How to Render an Architecture Diagram with Archify: A Complete CLI Guide

Archify converts typed JSON architecture descriptions into polished, interactive HTML/SVG diagrams through a four-stage CLI workflow: install, validate source JSON, render, and deliver.

Archify is an open-source diagramming tool from tt-a1i/archify that transforms structured JSON into production-ready architecture diagrams. Whether you need a quick draft or a version-controlled artifact for CI/CD, the rendering pipeline gives you precise control over quality, validation, and output formats. This guide walks through the complete workflow using the actual source implementation.

---

Install Archify and Prepare Your Environment

Begin by adding Archify as a global skill. The tool requires Node.js ≥ 18.

npx skills add tt-a1i/archify -g

After installation, you have two options for the source JSON:

• Start from an example: The repository bundles a validated example at examples/web-app.architecture.json.
• Write your own: Follow the strict schema defined in archify/schemas/architecture.schema.json.

The schema enforces node types, connection semantics, and layout constraints that the renderer expects.

---

Validate Architecture JSON Before Rendering

Run archify validate architecture to catch schema violations and layout problems early. This command is implemented in the CLI entry point archify/bin/archify.mjs, which delegates to validation logic before any rendering occurs.

node bin/archify.mjs validate architecture examples/web-app.architecture.json \
  --quality standard --json

What validation checks:

• Schema compliance against architecture.schema.json.
• Layout solvability (no overlapping nodes, valid edge routing).
• Optional source-evidence verification when --repo-root is provided.

The command returns a JSON receipt with diagnostics. Fix any errors before proceeding—invalid inputs fail hard in production mode.

---

Render a Quick Architecture Diagram

For rapid iteration, use the render sub-command. This invokes archify/renderers/architecture/render-architecture.mjs directly without final artifact checks.

node bin/archify.mjs render architecture examples/web-app.architecture.json \
  web-app.html

Command behavior:

• Outputs raw HTML to the specified path.
• Defaults to --quality standard (faster, smaller assets).
• Skips the post-render verification pipeline.

This is ideal for development loops where you need immediate visual feedback. However, the output is not guaranteed to meet Archify's style contracts.

---

Deliver Production-Ready Architecture Diagrams

The deliver command produces frozen, version-controlled artifacts suitable for CI/CD or release documentation. This is the recommended path when you render an architecture diagram for external stakeholders.

node bin/archify.mjs deliver architecture examples/web-app.architecture.json \
  web-app.html --quality showcase --open --json

deliver executes four stages:

1. Snapshot: Locks the JSON specification with a content hash.
2. Render: Invokes render-architecture.mjs with specified quality.
3. Artifact Check: Runs scripts/check-render-output.mjs to enforce SVG count limits, orthogonal arrow constraints, and composition rules.
4. Receipt: Writes a JSON manifest with provenance and checksums.

The --quality showcase flag enables higher-resolution assets and stricter layout constraints. Add --open to launch the result in your default browser.

---

Understanding the Rendering Architecture

The source code reveals a clean separation of concerns across these key files:

File	Purpose
archify/bin/archify.mjs	CLI entry point; parses sub-commands and routes to renderers.
archify/renderers/architecture/render-architecture.mjs	Core renderer implementation; consumed by both render and deliver.
archify/schemas/architecture.schema.json	Canonical JSON Schema for architecture source files.
scripts/check-render-output.mjs	Post-render verification suite enforcing visual contracts.

The CLI design follows a progressive disclosure pattern: guide suggests scenarios, validate prevents bad inputs, render optimizes for speed, and deliver guarantees correctness.

---

Summary

• Install Archify globally with npx skills add and Node ≥ 18.
• Author or adapt JSON following architecture.schema.json; use bundled examples as templates.
• Validate with archify validate architecture to catch errors before rendering.
• Render quickly with archify render for development feedback.
• Deliver confidently with archify deliver for production artifacts that pass strict post-render checks.

---

Frequently Asked Questions

What is the difference between render and deliver in Archify?

render invokes the architecture renderer directly and writes HTML without verification—fast but unverified. deliver performs a frozen snapshot, renders, runs artifact checks via scripts/check-render-output.mjs, and produces a receipt. Use render for iteration; use deliver for anything shipped to production.

How do I validate my architecture JSON against Archify's schema?

Run archify validate architecture <file> --quality <standard|showcase>. The command checks schema compliance, layout constraints, and optionally verifies source-evidence links when --repo-root is provided. Validation returns structured JSON diagnostics you can parse in CI pipelines.

Where is the core rendering logic implemented in the Archify source code?

The architecture renderer lives in archify/renderers/architecture/render-architecture.mjs. This module is imported and invoked by archify/bin/archify.mjs when processing render or deliver sub-commands. The renderer accepts quality parameters and repository context to produce HTML/SVG output.

What Node.js version does Archify require?

Archify requires Node.js 18 or higher. This ensures native support for the ES modules and web APIs used in the rendering pipeline. Install globally with npx skills add tt-a1i/archify -g to satisfy the runtime dependency.

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