How to Generate Architecture Diagrams from Typed JSON Using Archify

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

{
  "$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. 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 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.

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.

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.

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:

# 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:

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:

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, 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 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) 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.

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