api-reference

Archify JSON IR Schema Structure: Complete Reference Guide

September 2, 2026 tt-a1i/archify ↗

The Archify JSON IR schema is a declarative intermediate representation that defines architecture diagrams, data-flow graphs, and workflows through a standardized top-level object containing schema version, diagram type, metadata, components, connections, and optional boundaries and cards.

The Archify JSON IR (Intermediate Representation) is the core serialization format used by the tt-a1i/archify project to store, validate, and render technical diagrams. Every JSON IR file follows a strict schema that enables the Archify compiler to generate interactive HTML/SVG visualizations. This guide breaks down every property, field, and optional extension based on the actual source code implementation.

Core Schema Properties

Every Archify JSON IR object requires these six top-level properties, with two being optional:

Property	Type	Required	Purpose
`schema_version`	integer	Yes	Schema compatibility marker (current: `1`)
`diagram_type`	string	Yes	Diagram category: `"architecture"`, `"workflow"`, `"dataflow"`, or `"sequence"`
`meta`	object	Yes	Human-readable titles, subtitles, and output paths
`components`	array	Yes	Node definitions with position, size, and styling
`boundaries`	array	No	Visual grouping regions around components
`connections`	array	Yes	Directed edges between components
`cards`	array	No	Sidebar information panels

Metadata Section (`meta`)

The meta object controls presentation and output generation:

{
  "meta": {
    "title": "Sample System",
    "subtitle": "Demo of the Archify JSON IR",
    "output": "examples/sample-arch.html"
  }
}

title – Main heading displayed above the diagram
subtitle – Secondary descriptive text
output – Destination path for generated HTML (relative to project root)

Components Array

Components are the visual nodes in your diagram. Each component in the components array requires six core fields:

Required Component Fields

Field	Type	Description
`id`	string	Unique identifier referenced by connections
`type`	string	Styling classification: `"frontend"`, `"backend"`, `"cloud"`, `"external"`, `"database"`, `"messagebus"`, `"security"`
`label`	string	Primary display name on the node
`sublabel`	string	Secondary description (technology stack, version, etc.)
`pos`	`[x, y]`	Pixel coordinates of top-left corner
`size`	`[width, height]`	Node dimensions in pixels

Optional Component Fields

tag – Free-form string for custom styling hooks
row / col – Grid-based placement for auto-layout diagrams (see [examples/archify-repo-grid.architecture.json](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json))

{
  "components": [
    {
      "id": "backend",
      "type": "backend",
      "label": "API",
      "sublabel": "Node.js",
      "pos": [380, 200],
      "size": [140, 60],
      "tag": "critical-path"
    }
  ]
}

Boundaries Array (Optional)

Boundaries create visual grouping regions around components. As implemented in the Maka example at [examples/maka-architecture.architecture.json](https://github.com/tt-a1i/archify/blob/main/examples/maka-architecture.architecture.json), each boundary contains:

Field	Type	Description
`kind`	string	`"region"` for logical groups or `"security-group"` for trust boundaries
`label`	string	Description shown on the boundary
`wraps`	string[]	Array of component `id`s to enclose

{
  "boundaries": [
    {
      "kind": "region",
      "label": "Electron app + packages/runtime",
      "wraps": ["ui", "main", "session", "agentrun", "model", "toolrt", "storage", "permission"]
    },
    {
      "kind": "security-group",
      "label": "trust boundary",
      "wraps": ["permission", "storage"]
    }
  ]
}

Connections Array

Connections define directed edges between components with extensive visual customization:

Required Connection Fields

Field	Type	Description
`from`	string	Source component `id`
`to`	string	Destination component `id`

Optional Visual Modifiers

Field	Type	Description
`label`	string	Text displayed on the edge
`variant`	string	Line style: `"emphasis"`, `"dashed"`, `"security"`
`fromSide` / `toSide`	string	Anchor point: `"top"`, `"bottom"`, `"left"`, `"right"`
`via`	`[[x, y], ...]`	Poly-line routing waypoints

{
  "connections": [
    {
      "from": "frontend",
      "to": "backend",
      "label": "HTTP",
      "variant": "emphasis",
      "fromSide": "right",
      "toSide": "left"
    }
  ]
}

Cards Array (Optional)

Cards render as sidebar information panels for contextual documentation:

Field	Type	Description
`dot`	string	Leading bullet color (e.g., `"cyan"`, `"red"`, `"green"`)
`title`	string	Card header
`items`	string[]	Bullet-point content strings

{
  "cards": [
    {
      "dot": "cyan",
      "title": "Desktop surfaces",
      "items": [
        "apps/desktop: renderer, preload, main process",
        "Settings for models, bots, search, gateway, permissions",
        "Bots and open gateway share SessionManager as the public API"
      ]
    }
  ]
}

Complete Minimal Example

This valid Archify JSON IR demonstrates all required fields:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Sample System",
    "subtitle": "Demo of the Archify JSON IR",
    "output": "examples/sample-arch.html"
  },
  "components": [
    { "id": "client",   "type": "external", "label": "Client",   "sublabel": "Browser",     "pos": [40, 200],  "size": [120, 60] },
    { "id": "frontend", "type": "frontend", "label": "UI",       "sublabel": "React",       "pos": [200, 200], "size": [140, 60] },
    { "id": "backend",  "type": "backend",  "label": "API",      "sublabel": "Node.js",     "pos": [380, 200], "size": [140, 60] },
    { "id": "db",       "type": "database", "label": "Database", "sublabel": "PostgreSQL",  "pos": [580, 200], "size": [140, 60] }
  ],
  "connections": [
    { "from": "client",   "to": "frontend", "variant": "emphasis" },
    { "from": "frontend", "to": "backend",  "label": "HTTP",    "variant": "emphasis" },
    { "from": "backend",  "to": "db",       "label": "SQL",     "variant": "emphasis" }
  ]
}

Processing Pipeline

The Archify JSON IR schema enables a three-stage compilation flow:

Validation – The compiler checks schema_version compatibility and required field presence
Graph construction – components, connections, and boundaries build the internal representation
Rendering – SVG generation with interactive HTML output written to meta.output

Summary

The Archify JSON IR schema version 1 requires schema_version, diagram_type, meta, components, and connections
Components need id, type, label, sublabel, pos, and size; optionally use row/col for grid layouts
Boundaries group components by kind: "region" or "security-group" with a wraps id array
Connections support label, variant styling, fromSide/toSide anchors, and via waypoints for routing
Cards add sidebar documentation with colored dots, titles, and bullet items
Reference implementations exist in [examples/maka-architecture.architecture.json](https://github.com/tt-a1i/archify/blob/main/examples/maka-architecture.architecture.json) and [examples/archify-repo.architecture.json](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json)

Frequently Asked Questions

What is the current schema version for Archify JSON IR?

Archify JSON IR uses schema_version: 1 as of the latest tt-a1i/archify release. The compiler validates this field before processing and will reject incompatible future versions until updated.

Can I use Archify JSON IR for workflow and sequence diagrams?

Yes. The diagram_type field accepts "architecture", "workflow", "dataflow", or "sequence" values. While the core schema remains identical, the rendering engine applies diagram-specific layouts and styling rules based on this type declaration.

How do I position components automatically instead of using absolute coordinates?

Use the optional row and col fields in your component definitions. The [examples/archify-repo-grid.architecture.json](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json) file demonstrates this grid-based placement system, which calculates pos values automatically during compilation.

What connection variants are available for styling edges?

The variant field supports "emphasis" for bold highlighting, "dashed" for informational or optional flows, and "security" for trust-boundary crossings. Additional variants may be added in future schema versions based on the styling system in tt-a1i/archify.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

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

Ask your agent:

"Use Instagit MCP to understand how tt-a1i/archify works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →