How Archify's JSON IR Powers the Rendering Pipeline

Archify converts a typed, version-controlled JSON Intermediate Representation (IR) into standalone HTML diagrams through schema validation, typed renderer selection, and deterministic layout validation.

The tt-a1i/archify repository implements a robust diagram generation system centered on a JSON IR that ensures reproducible, schema-validated outputs. Understanding how this Archify JSON IR flows through the rendering pipeline reveals why the tool produces deterministic, self-contained HTML artifacts from pure JSON descriptions.

The JSON IR Structure

Every Archify diagram begins as a JSON file that must include two mandatory top-level fields: schema_version: 1 and diagram_type. The IR describes components, connections, metadata, and layout hints that drive the final visualization. A canonical example lives in examples/archify-repo.architecture.json, which demonstrates the required fields, component definitions, and the "cards" section that structures the HTML output.

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { 
    "title": "Archify", 
    "subtitle": "Agent skill → JSON IR → typed renderers → standalone HTML" 
  },
  "components": [],
  "connections": []
}

Step-by-Step Rendering Pipeline

Reading the Versioned IR

The pipeline begins by reading the JSON IR file from disk. The entry point validates that the required fields schema_version and diagram_type exist before proceeding. This step is visualized in the gallery page at scripts/gallery-template.html, which documents the flow from JSON input to renderer execution.

Schema Validation with AJV

Once loaded, the IR undergoes strict validation against a JSON-Schema using AJV validators generated in generated-validators.mjs. The validateSchema function in archify/renderers/shared/validator.mjs loads the appropriate validator for the specific diagram_type and runs the validation. If the IR violates the schema, the function throws a diagnostic error immediately.

// From archify/renderers/shared/validator.mjs
validateSchema(diagramType, jsonData) {
  const validator = this.validators.get(diagramType);
  const valid = validator(jsonData);
  if (!valid) {
    throw new Error(`Schema validation failed: ${JSON.stringify(validator.errors)}`);
  }
}

Typed Renderer Selection

The diagram_type field determines which of the five typed renderers handles the diagram: architecture, workflow, sequence, dataflow, or lifecycle. Each renderer implements specialized layout and geometry logic while sharing common utilities. For architecture diagrams, the main entry point is archify/renderers/architecture/render-architecture.mjs, which orchestrates the entire rendering process from lines 53-57.

Layout Computation and Validation

After selecting the renderer, the system computes component positions, connection routes, and boundaries. The architecture renderer then runs a series of "clean" validation gates to ensure deterministic geometry and spacing. The validateArchitecture() function invokes checks like cleanFlowProblems and cleanCrossingProblems to verify that the layout meets stability requirements.

// Validation gates inside render-architecture.mjs
validateArchitecture(layout) {
  this.cleanFlowProblems(layout);
  this.cleanCrossingProblems(layout);
  // Additional geometry checks...
}

Final Output Generation

Once the IR passes both schema and layout validation, the renderer constructs an SVG and wraps it in template.html. The archify/renderers/shared/cli.mjs module handles writing the standalone HTML file, with calls originating from render-architecture.mjs after successful validation. The pipeline also supports optional PNG and WebM exports.

CLI Usage and Examples

Render a diagram directly from the JSON IR using Node.js:

node archify/renderers/architecture/render-architecture.mjs \
  --diagram examples/archify-repo.architecture.json \
  --outPath out.html

Generate a JSON-only layout report for downstream tooling without producing HTML:

node archify/renderers/architecture/render-architecture.mjs \
  --diagram examples/archify-repo.architecture.json \
  --layout-json

Summary

• Archify JSON IR requires schema_version: 1 and diagram_type fields to ensure version compatibility and renderer selection.
• The AJV-based validator in archify/renderers/shared/validator.mjs enforces schema correctness before rendering begins.
• Typed renderers handle specific diagram types (architecture, workflow, sequence, dataflow, lifecycle) with specialized logic.
• Layout validation gates like cleanFlowProblems guarantee deterministic geometry and prevent rendering artifacts.
• The pipeline outputs standalone HTML artifacts via archify/renderers/shared/cli.mjs, with optional layout JSON exports available via CLI flags.

Frequently Asked Questions

What are the mandatory fields in an Archify JSON IR file?

Every JSON IR file must include schema_version set to 1 and a diagram_type string that specifies which renderer to invoke (such as "architecture" or "workflow"). These fields ensure the pipeline selects the correct validator and layout engine.

How does Archify validate the JSON IR before rendering?

Archify uses AJV validators defined in generated-validators.mjs. The validateSchema function in archify/renderers/shared/validator.mjs loads the schema for the specified diagram_type and throws a diagnostic error if the input JSON violates any schema constraints.

Can I extract just the layout data without generating HTML?

Yes. Passing the --layout-json flag to any renderer CLI (such as render-architecture.mjs) outputs a JSON description of the computed component positions and connection routes without writing the HTML artifact, useful for integrating with external tooling.

What happens if the layout validation fails?

If geometry checks like cleanFlowProblems or cleanCrossingProblems detect issues during validateArchitecture(), the pipeline halts and reports diagnostic information. This ensures that every generated diagram meets Archify's deterministic spacing and routing standards.

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