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

> Discover how Archify transforms typed JSON IR into diagrams. Learn about its validation and renderer pipeline for deterministic HTML/SVG visualizations. Explore tt-a1i/archify.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-09-10

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/workflow/README.md)
- **sequence** → [`archify/renderers/sequence/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/sequence/README.md)
- **lifecycle** → [`archify/renderers/lifecycle/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/lifecycle/README.md)
- **dataflow** → [`archify/renderers/dataflow/README.md`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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:

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md)** – Defines the JSON IR schema and validation rules
- **[`archify/renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/workflow/README.md)** – Handles workflow diagram transformations
- **[`archify/renderers/sequence/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/sequence/README.md)** – Processes sequence diagram IR
- **[`archify/renderers/lifecycle/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/lifecycle/README.md)** – Compiles lifecycle diagrams
- **[`archify/renderers/dataflow/README.md`](https://github.com/tt-a1i/archify/blob/main/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.