How Archify Transforms Typed JSON IR into HTML Diagrams

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

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

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:

<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 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, this format includes metadata fields for evidence links, styling recipes, and semantic identifiers. The schema definitions in 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 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.

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