# How Archify Transforms Typed JSON IR into HTML Diagrams

> Discover how Archify transforms typed JSON IR into interactive HTML diagrams using a five-stage pipeline including schema validation and SVG generation. Learn more today.

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

---

**Archify converts typed JSON intermediate representation (IR) into interactive HTML/SVG diagrams through a five-stage pipeline involving schema validation, IR compilation, geometry calculation, and semantic SVG generation.**

Archify is an open-source diagramming engine maintained in the tt-a1i/archify repository that bridges structured data and visual documentation. By accepting a strictly-typed JSON IR format, the tool generates deterministic, evidence-linked diagrams suitable for architectural visualization and workflow documentation. This article examines the technical pipeline that transforms raw JSON into interactive HTML diagrams with embedded metadata.

## The Five-Stage Rendering Pipeline

Archify processes JSON IR through a deterministic sequence that ensures visual consistency and preserves semantic relationships.

### Stage 1: Load and Validate the JSON IR

The pipeline begins when Archify ingests a JSON file (e.g., [`my-system.architecture.json`](https://github.com/tt-a1i/archify/blob/main/my-system.architecture.json)) and validates it against strict JSON Schema definitions.

In `archify/renderers/shared/validator.mjs`, the `validate` function checks the IR against schemas located in `archify/schemas/*.schema.json`. This validation step guarantees that nodes, edges, and metadata conform to expected types before compilation begins, preventing runtime errors during layout calculation.

### Stage 2: Compile the IR into a Layout Model

Once validated, the IR enters the compilation phase where abstract nodes and edges convert into concrete layout models.

For workflow diagrams, `archify/renderers/workflow/workflow-compiler.mjs` exposes the `compileWorkflow` function. For architectural diagrams, `archify/renderers/architecture/render-architecture.mjs` provides `renderArchitecture`. These compilers assign positions, dimensions, and visual attributes while preserving **evidence metadata** (repository links, line numbers) attached to nodes.

The compiler generates a **stable receipt**—a JSON description of the layout that enables deterministic re-rendering and visual regression testing.

### Stage 3: Calculate Geometry and Positioning

The geometry engine in `archify/renderers/shared/geometry.mjs` performs automatic layout calculations using grid, hierarchical, or signal-flow algorithms.

This module respects user-provided hints such as node groups and fixed coordinates, computing a stable view-box that ensures identical IR inputs produce identical SVG geometries. The deterministic positioning supports visual diff testing via `visual-check.test.mjs`.

### Stage 4: Generate Semantic SVG

The layout model serializes into an SVG string through the output pipeline.

As implemented in the rendering chain (utilizing `archify/renderers/shared/output-path.mjs`), the SVG generation embeds **semantic data-attributes** including node IDs, edge IDs, and evidence URLs directly into the markup. These attributes enable the viewer layer to expose tooltips, navigation, and proof-cards without requiring additional API round-trips.

### Stage 5: Render the Interactive Presentation Layer

When displayed in browsers, the SVG wraps inside [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html), which provides the interactive viewer container.

The viewer reads the embedded JSON IR (available via a `data-json` attribute) and the layout receipt to enable **proof-lab features** including zoom controls, pan navigation, legend display, and copy-ready prompts. This transforms the static SVG into a fully interactive HTML diagram.

## Key Architectural Benefits

Archify's pipeline delivers specific advantages for technical documentation workflows.

**Deterministic diagrams** ensure that identical IR inputs always produce identical visual outputs. Because the compiler writes a stable receipt, teams can implement visual regression testing to detect unintended layout changes.

**Evidence-first linking** allows nodes to carry repository evidence (file paths, line numbers, commit hashes). The viewer surfaces this metadata directly from the SVG data-attributes, making diagrams living documentation artifacts that reference actual source code.

**Extensible recipes** enable the compiler to respect metadata flags (e.g., `"diagramType": "blueprint"` or `"presentation": "editorial"`). The same IR can render in multiple visual styles without modifying the underlying data structure.

## Implementation Examples

The following examples demonstrate how to invoke Archify's rendering pipeline through different interfaces.

### CLI Rendering

Invoke the compiler directly from the command line to generate standalone SVG files:

```bash

# Install Archify globally

npm i -g @archify/cli

# Render an architecture diagram

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

```

The CLI loads the JSON, executes `validate()` from `validator.mjs`, runs the appropriate renderer (`render-architecture.mjs` or `workflow-compiler.mjs`), and writes the final SVG to disk.

### Programmatic Node.js Usage

Integrate Archify into build scripts or documentation generators:

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

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

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

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

console.log(svg);  // <svg data-json="..." ...>...</svg>

```

The `renderArchitecture` function internally orchestrates the compiler, geometry engine, and SVG serializer, returning both the markup and the layout receipt.

### Browser Embedding

Embed interactive diagrams directly in web applications:

```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 data attributes to enable node-finder functionality, proof cards, and interactive navigation.

## Summary

- Archify transforms typed JSON IR into HTML diagrams through five stages: validation, compilation, geometry calculation, SVG generation, and viewer rendering.
- The `validator.mjs` module enforces schema compliance before processing, while `workflow-compiler.mjs` and `render-architecture.mjs` handle type-specific compilation.
- **Stable receipts** generated during compilation enable deterministic rendering and visual regression testing across different environments.
- Semantic data-attributes embedded by the geometry engine preserve evidence links and metadata, allowing the [`template.html`](https://github.com/tt-a1i/archify/blob/main/template.html) viewer to display interactive proof-cards without additional API calls.
- The pipeline supports both CLI batch processing and programmatic integration via ES modules, making it suitable for CI/CD documentation workflows.

## Frequently Asked Questions

### What is the JSON IR format in Archify?

The JSON IR (Intermediate Representation) is a strictly-typed JSON structure that describes system components as nodes and relationships as edges. Located in files like [`archify/examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json), this format includes metadata fields for evidence links, styling recipes, and semantic identifiers. The schema definitions in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) enforce type safety before compilation begins.

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

Archify guarantees consistency through **stable receipts**—JSON documents generated during compilation that record exact node positions and layout parameters. The geometry engine in `archify/renderers/shared/geometry.mjs` uses deterministic algorithms that produce identical view-box coordinates for identical IR inputs. This enables visual regression testing by comparing receipt hashes or SVG outputs between builds.

### Can Archify render custom diagram types beyond workflows and architecture?

Yes. While the repository provides `compileWorkflow` for workflow diagrams and `renderArchitecture` for system architecture, the pipeline accepts custom compilers through the recipe metadata system. Developers can extend the base compiler classes to handle domain-specific IR formats, provided they output the standardized layout model that the geometry engine and SVG serializer expect.

### How does the viewer access evidence metadata without additional API calls?

The SVG generation stage embeds evidence URLs and node metadata directly into **data-attributes** on SVG elements (e.g., `data-evidence-url`, `data-node-id`). When [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) loads the diagram, the JavaScript viewer reads these attributes from the DOM to render tooltips and proof-cards. This design eliminates network dependencies, allowing diagrams to function as standalone HTML files with full interactivity.