How Archify Transforms Typed JSON IR into Diagrams: A Technical Deep Dive

Archify converts agent-generated typed JSON Intermediate Representation (IR) into deterministic HTML/SVG diagrams through a validation and renderer selection pipeline.

The tt-a1i/archify repository implements an agent-first rendering system where AI coding agents produce structured JSON descriptions of software architecture. This article explains how Archify ingests that typed JSON IR and compiles it into shareable, static diagrams without external dependencies.

The Four-Stage Transformation Pipeline

Archify separates architecture generation from visualization through a deterministic, data-driven pipeline.

Stage 1: Typed JSON IR Generation

AI agents such as Cursor, Claude Code, or Codex CLI generate a typed JSON IR file that describes nodes, edges, and the target visualization type. According to the source schema in archify/schemas/README.md, the IR must include a diagram_type field set to values like "workflow", "sequence", "lifecycle", or "dataflow".

Stage 2: Schema Validation

Before rendering, Archify validates the JSON structure against the official schema to guarantee structural correctness. This validation step ensures that required fields—such as nodes, edges, and diagram_type—are present and correctly typed, preventing runtime errors during compilation.

Stage 3: Renderer Selection

The diagram_type value determines which renderer module handles the transformation:

• workflow → archify/renderers/workflow/README.md
• sequence → archify/renderers/sequence/README.md
• lifecycle → archify/renderers/lifecycle/README.md
• dataflow → archify/renderers/dataflow/README.md

Each renderer is a specialized module that understands how to translate the typed IR into visual coordinates and SVG elements.

Stage 4: Deterministic Compilation

The selected renderer traverses the validated IR to compute node layouts, edge curves, and styling. It emits a stand-alone HTML file with embedded SVG that requires no external dependencies. Because the process is pure data-driven and deterministic, re-running the pipeline with the same input produces identical output, ensuring reproducible documentation.

Rendering Diagrams from Typed JSON IR

You can execute the transformation pipeline using the Archify CLI.

Creating the Input File

First, define your architecture in a JSON file following the typed IR schema:

{
  "diagram_type": "workflow",
  "nodes": [
    { "id": "browser", "label": "Browser" },
    { "id": "api", "label": "API Gateway" },
    { "id": "db", "label": "PostgreSQL" }
  ],
  "edges": [
    { "from": "browser", "to": "api", "label": "HTTPS request" },
    { "from": "api", "to": "db", "label": "SQL query" }
  ]
}

CLI Validation and Rendering

Run the validation and rendering commands:

# Validate the typed JSON IR against the schema

npx archify validate --json diagram.json

# Compile to a self-contained HTML/SVG diagram

npx archify render --input diagram.json --output diagram.html

These commands process the typed JSON IR and output a portable HTML file containing the rendered diagram.

Renderer Modules and File Structure

The transformation logic resides in specific renderer directories within the repository:

• archify/schemas/README.md – Defines the JSON IR schema and validation rules
• archify/renderers/workflow/README.md – Handles workflow diagram transformations
• archify/renderers/sequence/README.md – Processes sequence diagram IR
• archify/renderers/lifecycle/README.md – Compiles lifecycle diagrams
• archify/renderers/dataflow/README.md – Renders dataflow architectures

Each renderer operates independently, ensuring that changes to one diagram type do not affect others.

Summary

• Archify ingests typed JSON IR produced by AI agents and compiles it into deterministic diagrams.
• The pipeline includes schema validation, renderer selection based on diagram_type, and deterministic compilation to HTML/SVG.
• Renderers are modular and located in archify/renderers/{type}/README.md files.
• The CLI provides validate and render commands for standalone usage.
• Output is fully self-contained and reproducible, requiring no external services.

Frequently Asked Questions

What is typed JSON IR in Archify?

Typed JSON IR is a structured Intermediate Representation format that Archify uses as input. It includes strongly typed fields such as diagram_type, nodes, and edges, allowing AI agents to describe software architecture programmatically rather than drawing diagrams manually.

How does Archify ensure deterministic output?

Archify ensures determinism by validating the JSON IR against a strict schema before rendering and using pure data-driven compilation. The rendering process does not rely on external APIs or non-deterministic layout engines, so the same input always produces the same HTML/SVG output.

Can I modify a diagram after the initial render?

Yes. Because Archify retains the original typed JSON IR source, you can modify the JSON file—such as adding a new node or changing edge labels—and re-run npx archify render to generate an updated diagram. This iterative workflow supports incremental architecture updates without redrawing diagrams from scratch.

Which diagram types does Archify support?

Archify supports four core diagram types defined in the schema: workflow, sequence, lifecycle, and dataflow. Each type maps to a dedicated renderer module in the archify/renderers/ directory that specializes in transforming that specific IR structure into visual output.

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