# How Archify Transforms JSON IR into Diagrams: The Complete Pipeline

> Discover how Archify transforms JSON IR into diagrams via a five-stage pipeline. Learn about schema validation, layout compilation, stable geometry, semantic SVG serialization, and interactive viewing.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-09-08

---

**Archify transforms JSON IR into diagrams through a deterministic five-stage pipeline that validates input against JSON schemas, compiles abstract nodes into concrete layout models, computes stable geometry, serializes to semantic SVG, and wraps the output in an interactive viewer.**

Archify, an open-source visualization tool from the `tt-a1i/archify` repository, converts **JSON-based intermediate representations (IR)** of systems into interactive, verifiable SVG diagrams. This transformation process bridges the gap between structured data definitions and visual documentation, enabling automated generation of architecture and workflow diagrams directly from machine-readable specifications.

## The Five-Stage Transformation Pipeline

The transformation from JSON IR to rendered diagram follows a strict pipeline implemented across the renderer modules. Each stage produces validated artifacts that feed into the next, ensuring deterministic output.

### 1. Load and Validate the JSON IR

The process begins when Archify ingests a JSON file (for example, [`my-system.architecture.json`](https://github.com/tt-a1i/archify/blob/main/my-system.architecture.json)). The **validator** module located at `archify/renderers/shared/validator.mjs` parses the input against strict **JSON schemas** stored in `archify/schemas/*.schema.json`. This validation step guarantees that the IR contains well-formed nodes, edges, and metadata before compilation begins. Invalid schemas trigger diagnostic collection that helps users correct structural errors early in the pipeline.

### 2. Compile the Intermediate Representation

Once validated, the parsed object enters the **compiler** phase. Archify employs specialized compilers depending on the diagram type:
- **Workflow diagrams**: Processed by `compileWorkflow` in `archify/renderers/workflow/workflow-compiler.mjs`
- **Architecture diagrams**: Handled by `renderArchitecture` in `archify/renderers/architecture/render-architecture.mjs`

These compilers transform abstract IR nodes and edges into concrete layout models. During compilation, the system assigns positions, dimensions, and visual attributes while preserving attached **evidence** such as code repository links, file paths, and line numbers. The compiler also generates a **stable receipt**—a JSON description of the layout—that enables visual regression testing and deterministic re-rendering.

### 3. Compute Layout and Geometry

The compiled model flows into the **geometry engine** at `archify/renderers/shared/geometry.mjs`. This module performs automatic layout calculations using strategies including grid-based positioning, hierarchical layouts, and signal-flow arrangements. The geometry engine respects user-provided hints such as node groups or fixed coordinates, producing a stable view-box that ensures identical IR inputs always generate identical SVG geometries. This deterministic approach, implemented in the geometry calculations, supports reproducible builds and visual diff testing via `visual-check.test.mjs`.

### 4. Generate Semantic SVG

With geometry calculated, Archify serializes the layout model into an SVG string. The SVG output includes **semantic data-attributes** attached to each graphical element—these encode node IDs, edge IDs, and evidence URLs directly into the markup. This embedding strategy eliminates extra round-trips to servers when users interact with the diagram, enabling immediate tooltip display and navigation to source code. The CLI writes this output via `archify/renderers/shared/output-path.mjs`, while programmatic APIs return the SVG string directly.

### 5. Render the Interactive Presentation Layer

When diagrams display in browsers, the raw SVG wraps inside a viewer template located at [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html). This presentation layer adds UI controls for zoom, pan, and legend display. Crucially, the viewer reads the embedded JSON IR (available through a `data-json` attribute) and the layout receipt to enable **proof-lab features**—interactive proof cards, copy-ready prompts, and node-finder functionality that connect visual elements back to their source evidence.

## Practical Implementation: CLI and Programmatic APIs

Archify exposes the transformation pipeline through multiple interfaces, allowing integration into build systems, documentation generators, and web applications.

### Rendering from the Command Line

Use the CLI to transform JSON files into SVG diagrams with a single command:

```bash

# Install Archify globally

npm i -g @archify/cli

# Transform an architecture IR into SVG

archify render my-system.architecture.json \
  --type architecture \
  --output diagram.svg

```

The CLI internally invokes `validator.mjs` for schema checking, routes to `render-architecture.mjs` for compilation, and writes the final SVG to the specified output path.

### Using the Compiler Programmatically

For Node.js applications, import the renderer modules directly to transform JSON IR within your code:

```javascript
import { readFileSync } from 'fs';
import { renderArchitecture } from '@archify/renderers/architecture/render-architecture.mjs';
import { validate } from '@archify/renderers/shared/validator.mjs';

// Load the JSON IR
const ir = JSON.parse(readFileSync('my-system.architecture.json'));

// Validate against architecture schema
validate(ir, 'architecture');

// Compile and generate SVG with quality profile
const { svg } = renderArchitecture({ 
  ir, 
  qualityProfile: 'showcase' 
});

console.log(svg);  // Outputs: <svg ...>

```

The `renderArchitecture` function orchestrates calls to the compiler, geometry engine, and SVG serializer, returning the final markup along with metadata.

### Embedding Diagrams in Web Applications

For browser-based documentation, load Archify from CDN and render diagrams client-side:

```html
<div id="archify-viewer"></div>
<script type="module">
  import { renderArchitecture } from 'https://cdn.jsdelivr.net/npm/@archify/renderers/architecture/render-architecture.mjs';

  const ir = {/* your JSON IR */};
  const { svg, receipt } = await renderArchitecture({ 
    ir, 
    qualityProfile: 'showcase' 
  });

  document.getElementById('archify-viewer').innerHTML = `
    <archify-viewer 
      data-json='${JSON.stringify(ir)}' 
      data-receipt='${JSON.stringify(receipt)}'>
      ${svg}
    </archify-viewer>`;
</script>

```

The `archify-viewer` web component consumes the embedded JSON and receipt to enable interactive features without requiring server-side processing.

## Summary

- **Validation-first pipeline**: Archify validates JSON IR against schemas in `archify/schemas/` using `validator.mjs` before compilation begins.
- **Deterministic compilation**: The compilers in `workflow-compiler.mjs` and `render-architecture.mjs` generate stable receipts that ensure consistent geometry across renders.
- **Geometry engine**: `archify/renderers/shared/geometry.mjs` computes layouts that respect user hints while maintaining view-box stability.
- **Semantic SVG output**: Generated diagrams embed data-attributes containing node IDs and evidence URLs for rich interactivity.
- **Evidence integration**: The system preserves code repository links and line numbers throughout the pipeline, surfacing them in the viewer template at [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html).

## Frequently Asked Questions

### What is JSON IR in the context of Archify?

JSON IR (Intermediate Representation) is a structured JSON format that describes system components, relationships, and metadata. In Archify, this representation serves as the single source of truth for diagram generation, containing node definitions, edge connections, and optional evidence links to source code repositories.

### How does Archify ensure diagram consistency across renders?

Archify achieves consistency through **stable receipts** generated by the compiler. These receipts capture the computed layout decisions, allowing the geometry engine to reproduce identical positioning across multiple render passes. This determinism enables visual regression testing where `visual-check.test.mjs` compares generated receipts to detect unintended changes.

### Can Archify render different diagram types from the same IR?

While Archify uses specialized compilers for different diagram categories, the same IR structure can feed multiple renderers depending on the **recipe metadata** embedded in the JSON. The `compileWorkflow` and `renderArchitecture` functions interpret the IR through different layout algorithms, allowing the same system description to generate both workflow diagrams and architectural blueprints.

### What evidence features does Archify embed in generated diagrams?

Archify implements an **evidence-first** architecture where nodes can store repository file paths, line numbers, and URLs. During SVG generation, these references embed as semantic data-attributes. The viewer component reads these attributes to display proof cards and direct navigation links, transforming static diagrams into living documentation connected to actual source code.