How Archify Transforms JSON IR into Diagrams: The Complete Pipeline

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

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

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:

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

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.

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