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

> Learn to render architecture diagrams with Archify CLI. This guide covers installation, validation, rendering, and delivery for polished SVG diagrams from JSON.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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**.

```bash
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`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.architecture.json).
- **Write your own**: Follow the strict schema defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/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.

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

```

**What validation checks:**

- Schema compliance against [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/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.

```bash
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.

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.