# How to Generate Architecture Diagrams from Typed JSON Using Archify

> Easily generate interactive architecture diagrams from typed JSON using Archify. This powerful tool validates and renders your system architecture into clear HTML visualizations. Learn how now.

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

---

**Archify converts strictly-typed JSON descriptions of system architecture into deterministic, interactive HTML diagrams through a four-step validation and rendering pipeline.**

The open-source tool Archify (`tt-a1i/archify`) eliminates manual diagram maintenance by turning structured data into visual documentation. By defining nodes, edges, and component roles in a typed JSON format, you can generate architecture diagrams that are reproducible, searchable, and self-contained for sharing.

## Understanding the Typed JSON Schema

Before generating diagrams, your JSON must conform to the **Archify schema** defined in [[`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md). The schema requires specific top-level keys that describe both the system structure and visual presentation.

A valid architecture JSON includes:

- **`$schema`**: Reference to the architecture schema URL
- **`meta`**: Visual presets (e.g., `signal-flow`) and locale settings  
- **`nodes`**: Array of objects with `id`, `label`, and `role` (frontend, service, database, etc.)
- **`edges`**: Array of connection objects defining `source`, `target`, and relationship labels

```json
{
  "$schema": "https://raw.githubusercontent.com/tt-a1i/archify/main/archify/schemas/architecture.schema.json",
  "meta": {
    "visual_preset": "signal-flow",
    "locale": "en"
  },
  "nodes": [
    { "id": "browser", "label": "Browser", "role": "frontend" },
    { "id": "web-app", "label": "Web App", "role": "service" },
    { "id": "api", "label": "API Server", "role": "service" },
    { "id": "postgres", "label": "PostgreSQL", "role": "database" }
  ],
  "edges": [
    { "source": "browser", "target": "web-app", "label": "HTTPS" },
    { "source": "web-app", "target": "api", "label": "REST" },
    { "source": "api", "target": "postgres", "label": "SQL" }
  ]
}

```

## The Four-Step Workflow to Generate Architecture Diagrams

Archify processes your typed JSON through a deterministic pipeline implemented in [`archify/bin/archify.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs). Each step ensures structural correctness before rendering the final visual output.

### 1. Generate the Typed JSON Source

Create your architecture definition either manually or via an AI agent prompted to output typed JSON. The file must declare all system components as nodes and their interactions as edges. Store this with the [`.architecture.json`](https://github.com/tt-a1i/archify/blob/main/.architecture.json) extension to match the repository conventions.

### 2. Validate Structure and Reachability

Run Archify's bundled validators to check schema compliance, layout feasibility, and graph reachability. If validation fails, the CLI returns a single JSON diagnostic pinpointing the exact property to fix.

```bash
node archify/bin/archify.mjs validate architecture your-file.architecture.json

```

### 3. Preview Changes in Real-Time

Use the **watch-and-reload** loop to iterate on your diagram without regenerating files manually. This mode monitors the JSON file for changes, validates on each save, and renders only after passing validation—preserving the last-good view when errors occur.

```bash
node archify/bin/archify.mjs preview architecture examples/web-app.architecture.json /tmp/web-app.html --quality showcase

```

### 4. Deliver the Final Artifact

The `deliver` command generates a self-contained HTML file embedding both the rendered diagram and the source JSON. This creates a **verifiable artifact**: reviewers can trace any node back to the exact line and commit that generated it.

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

```

The `--json` flag emits a JSON receipt to `stderr` containing metadata about the build.

## Installation and Common CLI Patterns

Install Archify globally using the skills registry, then invoke commands via Node.js:

```bash

# Install once

npx skills add tt-a1i/archify -g

# Generate final diagram

node archify/bin/archify.mjs deliver architecture path/to/your-architecture.json out.html --quality showcase

```

### Comparing Architecture Versions

Track evolutionary changes between two JSON snapshots using the `compare` command, which generates a delta visualization:

```bash
node archify/bin/archify.mjs compare architecture base.json head.json delta.html --json

```

### Interactive Guidance

Generate contextual diagrams from natural language descriptions using the built-in guide feature:

```bash
node archify/bin/archify.mjs guide "Show an API request with Redis cache miss" --json

```

## Why Deterministic Output Matters

Archify guarantees that **the same typed JSON always produces the same HTML/SVG output**. This determinism makes architecture reviews trustworthy—there are no hidden layout adjustments or manual positioning drift between exports. Because the source JSON is embedded directly in the generated HTML file, documentation remains traceable to its exact source commit.

## Summary

- **Archify** transforms typed JSON into interactive architecture diagrams through the `archify.mjs` CLI entry point.
- The workflow follows four deterministic stages: **Generate**, **Validate**, **Preview**, and **Deliver**.
- Source files must conform to the schema defined in [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md), specifying nodes, edges, roles, and visual metadata.
- The **`deliver`** command creates self-contained HTML artifacts that embed the original JSON for full traceability.
- **`preview`** mode provides watch-and-reload functionality for iterative development without invalid state rendering.
- Output is fully reproducible, enabling reliable version comparison via the **`compare`** command.

## Frequently Asked Questions

### What is the required schema for Archify typed JSON?

Archify requires JSON files to declare the `$schema` key pointing to [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) in the repository's `archify/schemas/` directory. The document must include `nodes` (with `id`, `label`, and `role`) and `edges` (with `source` and `target`) arrays, plus optional `meta` configuration for visual presets. See [[`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) for the complete specification.

### How do I validate my architecture JSON before generating the diagram?

Run `node archify/bin/archify.mjs validate architecture <filename>` to execute the bundled validators (schema, layout, and reachability). The CLI returns precise JSON diagnostics if the file violates structural rules or contains unreachable nodes, allowing you to fix errors before rendering.

### Can I compare two versions of an architecture diagram?

Yes. Use the `compare` subcommand to visualize differences between two JSON snapshots: `node archify/bin/archify.mjs compare architecture base.json head.json output.html`. This generates an interactive delta diagram showing structural changes between versions.

### What output formats does Archify support?

Archify primarily generates **self-contained HTML files** that include the interactive diagram viewer and embedded source JSON. From the HTML interface, you can export static **PNG**, **SVG**, or **WebM** files using the built-in Export button. The HTML itself requires no runtime dependencies beyond a standard web browser.