Archify JSON Intermediate Representation (IR): Schema-Validated Diagram Rendering

The Archify JSON Intermediate Representation is a versioned, schema-validated data structure that serves as the canonical contract between diagram authors and the rendering engine, enabling deterministic SVG generation through strict validation before layout calculations.

The Archify JSON Intermediate Representation (IR) is the central data format powering the tt-a1i/archify diagram rendering pipeline. Unlike traditional tools that parse raw text directly into graphics, Archify first converts diagrams into a structured JSON document that captures semantic relationships, layout metadata, and styling information. This intermediate layer creates a stable, version-controlled boundary between diagram logic and rendering implementation.

What is the Archify JSON IR?

The JSON IR acts as a stable contract between diagram authors and Archify's rendering engine. Each IR document includes a schema_version field that guarantees backward compatibility—files validating today will render identically on future 2.x releases. When breaking changes occur, the version bumps and older files receive clear validation errors rather than silent rendering failures.

Six Critical Purposes of the JSON IR

Schema Validation Before Rendering

Before any layout work begins, Archify validates incoming JSON against strict typed schemas. The system uses AJV (Another JSON Schema Validator) through archify/renderers/shared/validator.mjs to check against diagram-specific schemas: archify/schemas/workflow.schema.json, archify/schemas/sequence.schema.json, archify/schemas/dataflow.schema.json, archify/schemas/lifecycle.schema.json, or archify/schemas/architecture.schema.json. This prevents unknown fields from silently corrupting output and eliminates runtime npm or network dependencies by shipping a generated validator with the skill.

Version-Stable Rendering

The schema_version field in every IR document ensures deterministic rendering across releases. When the Archify team introduces breaking schema changes, they increment the version number and reject outdated documents with explicit error messages. This policy, documented in archify/schemas/README.md, guarantees that archived diagrams remain visually stable years after creation.

Diff-Friendly Editing

Because the IR consists of plain JSON objects, version control systems display changes as precise git diff hunks. Modifying a node's coordinates, swapping themes, or adjusting edge labels produces isolated, readable diffs. Claude (the LLM) can perform incremental edits to the IR without regenerating entire diagrams, preventing visual drift between iterations.

Separation of Concerns

The IR cleanly isolates semantic information (nodes, edges, lanes, phases) from rendering concerns (SVG path generation, CSS animations, layout heuristics). Renderers consume the validated IR, perform geometry calculations, and output HTML/SVG. This architecture makes renderers focused, testable units that don't need to parse raw diagram syntax.

Extensible Architecture

New diagram types integrate by defining a new schema in archify/schemas/ and implementing a matching renderer. Because all renderers share the validation pipeline in archify/renderers/shared/validator.mjs, the system maintains consistency as it grows. Each new diagram type automatically inherits schema validation and version checking.

Performance Optimization

Validation occurs before expensive layout calculations begin. The standalone AJV validators process quickly, rejecting malformed input early in the pipeline. This prevents wasted computational effort on geometry calculations for invalid diagrams.

JSON Schema Structure and File Locations

Archify maintains separate JSON Schema files for each diagram type in the archify/schemas/ directory:

• archify/schemas/workflow.schema.json: Defines lanes, phases, nodes, and edges for workflow diagrams
• archify/schemas/sequence.schema.json: Handles sequence diagram lifelines and messages
• archify/schemas/dataflow.schema.json: Manages dataflow diagram components and data streams
• archify/schemas/lifecycle.schema.json: Covers state machine transitions and states
• archify/schemas/architecture.schema.json: Defines architecture diagram elements and relationships

The archify/schemas/README.md documents the versioning policy and schema evolution rules.

Workflow Example: Creating and Rendering the JSON IR

Below is a minimal workflow IR that satisfies workflow.schema.json. Save this as my-workflow.json:

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": {
    "title": "Sample Order Workflow"
  },
  "lanes": [
    { "id": "frontend", "label": "Frontend" },
    { "id": "backend", "label": "Backend" }
  ],
  "phases": [
    { "id": "order", "label": "Order", "lane": "frontend" },
    { "id": "process", "label": "Process", "lane": "backend" }
  ],
  "nodes": [
    { "id": "ui", "label": "UI", "phase": "order" },
    { "id": "api", "label": "API", "phase": "process" }
  ],
  "edges": [
    { "source": "ui", "target": "api", "label": "Submit Order" }
  ]
}

Render the diagram using the CLI entry point at archify/bin/archify.mjs:

node archify/bin/archify.mjs render workflow my-workflow.json > diagram.html

The CLI execution follows this pipeline:

1. Loads my-workflow.json from disk
2. Validates the structure against archify/schemas/workflow.schema.json using the AJV validator in archify/renderers/shared/validator.mjs
3. Passes the verified IR to archify/renderers/workflow/render-workflow.mjs
4. Generates a self-contained HTML file with embedded SVG and optional CSS animations

Renderer Implementation and IR Consumption

Renderers do not handle raw parsing or validation logic. The render-workflow.mjs module receives a validated JavaScript object containing the IR data and focuses exclusively on geometry calculations and SVG generation. This design allows renderers to assume input correctness, eliminating defensive coding patterns and reducing complexity.

The validator guarantees that required fields like schema_version, diagram_type, nodes, and edges exist and contain valid types before the renderer executes. This contract enables renderers to access properties directly without null checks for schema-level validation failures.

Summary

• The Archify JSON Intermediate Representation provides a versioned, schema-validated contract between diagram authors and the rendering engine.
• AJV validation occurs in archify/renderers/shared/validator.mjs before any layout calculations, rejecting malformed input early.
• The schema_version field ensures deterministic rendering across releases, with breaking changes triggering explicit version bumps.
• Plain JSON structure enables diff-friendly editing and incremental modifications by Claude or human authors.
• Separation of concerns isolates semantic data (nodes, edges) from rendering logic (SVG generation), making components testable.
• New diagram types extend the system by adding schemas to archify/schemas/ and implementing targeted renderers.

Frequently Asked Questions

What is the Archify JSON Intermediate Representation?

The Archify JSON Intermediate Representation is a structured data format that captures the semantic graph and layout metadata of diagrams before rendering. Located in the tt-a1i/archify repository, it serves as a canonical intermediate layer between raw diagram descriptions and final SVG/HTML output. The IR uses JSON Schema validation to ensure structural correctness and version compatibility.

How does schema versioning work in Archify?

Every IR document includes a schema_version integer that locks the file to a specific schema revision. According to archify/schemas/README.md, valid files continue rendering identically across all future 2.x releases. When maintainers introduce breaking changes, they increment the schema version and update the validator, causing older files to fail validation with clear error messages rather than rendering incorrectly.

Why does Archify validate JSON before rendering?

Validation occurs in archify/renderers/shared/validator.mjs using pre-compiled AJV validators to catch schema violations before expensive layout calculations begin. This early rejection prevents wasted CPU cycles on geometry calculations for malformed diagrams and eliminates silent failures from unknown fields. The approach also removes runtime npm dependencies since validators ship with the skill.

Can I manually edit the Archify JSON IR?

Yes, the JSON IR supports manual editing because it uses plain JSON objects that produce readable git diff output. Claude and human authors can modify specific properties—such as node coordinates, edge labels, or theme settings—without regenerating the entire diagram structure. Changes validate against the appropriate schema (e.g., archify/schemas/workflow.schema.json) before rendering, ensuring manual edits maintain structural integrity.

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