How Archify Transforms JSON IR into HTML and SVG Diagrams

Archify transforms JSON IR into HTML/SVG diagrams through a three-stage pipeline: schema validation with AJV, typed rendering to SVG elements, and HTML embedding via a lightweight bootstrap script.

The JSON Intermediate Representation (IR) is the core data structure that powers Archify's architecture visualization toolkit. This typed format captures nodes, edges, layout coordinates, and visual styling in a deterministic, version-controlled schema. The transformation from raw JSON IR to browser-ready diagrams follows a clean separation between validation, rendering, and mounting concerns.

Understanding the JSON IR Schema

Before any rendering occurs, Archify validates the JSON IR against a strict JSON-Schema definition. This ensures structural integrity and provides clear error messages when the IR deviates from expectations.

The schema requires fields such as id, type, label, row, and col for nodes, with optional modifiers like sublabel, position, and style. The schema_version field (currently version 1) enables safe evolution of the format across releases.

{
  "schema_version": 1,
  "nodes": [
    {"id":"agents","type":"agent","label":"Agents"},
    {"id":"ir","type":"messagebus","label":"JSON IR","sublabel":"schema v1"}
  ],
  "edges": [
    {"from":"agents","to":"ir","label":"write IR"}
  ]
}

The validation layer resides in archify/schema/ir-schema.json and is invoked by archify/renderers/validate-ir.mjs using the AJV validator.

The SVG Rendering Pipeline

Once validated, the IR flows into the typed renderer implemented in archify/renderers/svg-renderer.mjs. This module walks the IR structure and constructs SVG elements programmatically.

Node rendering creates <g> container elements with standardized data attributes:

• data-node-id — the node's unique identifier
• data-node-label — display text for tooltips
• data-node-type — visual classification (agent, service, database, etc.)

Edge rendering generates <path> elements with arrow markers and optional <title> tags for accessibility. The renderer respects explicit coordinates when provided in the IR, or delegates to a deterministic layout engine (such as dagre) when positions are omitted.

The output is pure SVG markup with embedded CSS classes for theming, requiring no external rendering dependencies.

Embedding Diagrams in HTML

The final stage injects the generated SVG into a web page. Archify provides archify/renderers/render-mount.mjs as a lightweight helper that:

1. Locates the JSON IR (inline <script> block or fetched resource)
2. Validates and parses the IR
3. Invokes renderDiagram(ir, container) to produce SVG
4. Appends the result to a specified DOM container

This design produces zero-install diagrams — the resulting HTML file contains only vanilla JavaScript and self-contained SVG, with no build-step dependencies for viewers.

Browser Integration Example

<script type="application/json" id="archify-ir">
{
  "schema_version": 1,
  "nodes": [
    {"id":"agents","type":"agent","label":"Agents"},
    {"id":"ir","type":"messagebus","label":"JSON IR","sublabel":"schema v1"}
  ],
  "edges": [
    {"from":"agents","to":"ir","label":"write IR"}
  ]
}
</script>

<div id="archify-root"></div>

<script type="module">
import { renderDiagram } from '@tt-a1i/archify';
const ir = JSON.parse(document.getElementById('archify-ir').textContent);
renderDiagram(ir, document.getElementById('archify-root'));
</script>

The renderDiagram function handles validation caching, renderer instantiation, and DOM insertion in a single call.

Server-Side and CLI Rendering

The same pipeline operates outside the browser for documentation builds and CI artifacts. The renderDiagramSync function in archify/renderers/svg-renderer.mjs provides synchronous rendering for Node.js environments.

import { readFileSync, writeFileSync } from 'node:fs';
import { renderDiagramSync } from '@tt-a1i/archify/renderers/svg-renderer.mjs';

const ir = JSON.parse(readFileSync('examples/archify-repo.architecture.json', 'utf-8'));
const svg = renderDiagramSync(ir);

writeFileSync('dist/diagram.svg', svg);

This enables headless generation of architecture diagrams as part of automated documentation pipelines.

Key Implementation Files

File	Purpose
archify/schema/ir-schema.json	JSON-Schema definition for IR validation
archify/renderers/validate-ir.mjs	AJV-based validation wrapper
archify/renderers/svg-renderer.mjs	Core SVG generation logic
archify/renderers/render-mount.mjs	Browser mounting helper
examples/archify-repo.html	Full demo page showing end-to-end transformation
examples/archify-repo.architecture.json	Sample IR illustrating schema conventions

Summary

• Validation first: All JSON IR is checked against archify/schema/ir-schema.json using AJV before rendering
• Typed SVG generation: archify/renderers/svg-renderer.mjs converts validated IR into accessible <g> and <path> elements with data attributes
• Flexible embedding: Browser apps use renderDiagram(), while server contexts call renderDiagramSync()
• Deterministic output: Explicit coordinates or seeded layout ensures reproducible diagrams for version control comparison
• Zero dependencies: Generated HTML/SVG requires no external libraries to display

Frequently Asked Questions

What is JSON IR in Archify?

JSON IR (Intermediate Representation) is a typed, schema-versioned format that describes architecture diagrams as structured data. It encodes nodes with identifiers, types, labels, and positions, plus edges defining relationships. According to the archify/schema/ir-schema.json source code, the current schema_version is 1, and the format requires fields like id, type, label, row, and col for valid node definitions.

How does Archify validate the JSON IR before rendering?

Validation occurs through AJV (Another JSON Schema Validator) as implemented in archify/renderers/validate-ir.mjs. The validator loads archify/schema/ir-schema.json and checks that the input IR conforms to all required fields, correct types, and structural constraints. Invalid IR triggers descriptive error messages before any rendering begins, preventing broken diagrams from reaching output.

Can Archify render diagrams without a browser?

Yes. The renderDiagramSync function exported from archify/renderers/svg-renderer.mjs operates in Node.js environments without DOM dependencies. It returns SVG markup as a string, suitable for writing to files, embedding in static site generators, or serving through documentation APIs. This server-side capability uses the same validation and rendering pipeline as the browser implementation.

What makes Archify's output deterministic for version control?

The JSON IR supports explicit coordinate fields (row, col, or position objects) that bypass layout calculation. When coordinates are embedded in the IR, the renderer places elements identically on every run. For layouts requiring computation, Archify uses seeded deterministic algorithms rather than stochastic layout engines, ensuring that identical IR produces pixel-identical SVG output suitable for diff-based version control workflows.

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