How to Define an Architecture Diagram in Archify's JSON IR Format

Archify represents architecture diagrams as a JSON Intermediate Representation (IR) that validates against a strict schema requiring schema_version, diagram_type, meta, and at least one component object.

Archify is an open-source visualization engine that converts structured JSON into standalone HTML architecture diagrams. To define a diagram, you create a JSON IR file that conforms to the Architecture Schema enforced by the AJV validator in the tt-a1i/archify repository.

Core JSON IR Structure

Every architecture diagram must include seven top-level properties. According to archify/schemas/architecture.schema.json, the document root requires:

• schema_version: Must be the integer 1 (locked constant)
• diagram_type: Must be the string "architecture"
• meta: Object containing at least a title string
• components: Array containing at least one component object
• layout: Optional layout hints (grid mode, origin, gaps)
• boundaries: Optional array grouping components into regions
• connections: Optional array of directed edges between components
• cards: Optional annotation cards displayed alongside the diagram

Defining Metadata with the meta Object

The meta object in examples/archify-repo.architecture.json demonstrates the required structure. Only title is mandatory, but you can configure rendering behavior through additional fields:

• subtitle: Brief description shown below the title
• locale: Language code ("en" or "zh-CN")
• output: File path for the generated HTML artifact
• repository: GitHub repository link with 40-character SHA
• views: Guided view definitions referencing common.schema.json
• viewBox: Explicit SVG viewport dimensions

Example from the source:

"meta": {
  "title": "Archify",
  "subtitle": "Agent skill → JSON IR → typed renderers → standalone HTML",
  "output": "examples/archify-repo.html"
}

Creating Components

Components are the visual nodes in your diagram. Each entry in the components array must include id, type, and label per the schema defined in archify/schemas/common.schema.json.

Required Component Fields

• id: Unique string identifier for referencing in connections
• type: Enum value limited to frontend, backend, database, cloud, security, messagebus, or external
• label: Display text for the node

Optional Positioning and Styling

• pos: Array [x, y] with non-negative coordinates
• size: Array [width, height] with positive integers
• row/col: Grid placement when layout.mode is "grid"
• sublabel, tag, brand: Additional descriptive text
• sources: Code reference objects with path and line numbers

Example component definition from the reference implementation:

{
  "id": "ir",
  "type": "messagebus",
  "label": "JSON IR",
  "sublabel": "schema_version: 1",
  "pos": [400, 300],
  "size": [140, 60]
}

Grouping Components with Boundaries

Boundaries wrap components into visual regions or security groups. Each boundary object specifies:

• kind: Either "region" or "security-group"
• label: Display name for the boundary
• wraps: Array of component IDs to include

From examples/archify-repo.architecture.json:

{
  "kind": "region",
  "label": "archify/ skill package",
  "wraps": ["ir", "schemas", "renderers", "template", "checker"]
}

Establishing Connections

The connections array defines directed edges using component IDs. The schema in architecture.schema.json supports sophisticated routing and styling:

• from/**to**: Source and target component IDs (required)
• variant: Visual style enum (default, emphasis, security, dashed)
• fromSide/**toSide**: Anchor attachment (left, right, top, bottom)
• route: Routing algorithm (auto, straight, orthogonal-h, orthogonal-v)
• via: Array of intermediate [x, y] points for custom paths
• label: Text displayed on the edge
• labelAt, labelDx, labelDy, labelSegment: Fine-tuned label placement
• width: Line thickness in pixels

Example connection with emphasis styling:

{
  "from": "user",
  "to": "agents",
  "variant": "emphasis"
}

Adding Explanatory Cards

Cards add annotation "sticky notes" to diagrams. Each card requires:

• dot: Color marker from the palette (cyan, emerald, rose, etc.)
• title: Heading string
• items: Array of bullet-point strings

Example card from the demo:

{
  "dot": "emerald",
  "title": "Render path",
  "items": [
    "JSON IR pins schema_version: 1",
    "Five typed renderers: architecture / workflow / sequence / dataflow / lifecycle",
    "template.html owns theme toggle and 4× export"
  ]
}

Validating Your JSON IR

Archify validates documents against archify/schemas/architecture.schema.json using AJV (Another JSON Schema Validator) as declared in archify/package.json. The validation ensures:

• Required fields are present
• Component types match the enum in common.schema.json
• Connection endpoints reference existing component IDs
• Schema version matches the expected constant

Complete Code Examples

Minimal Valid Diagram

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "My Simple Architecture"
  },
  "components": [
    {
      "id": "frontend",
      "type": "frontend",
      "label": "Web Frontend",
      "pos": [100, 200],
      "size": [120, 60]
    },
    {
      "id": "backend",
      "type": "backend",
      "label": "API Service",
      "pos": [300, 200],
      "size": [120, 60]
    }
  ],
  "connections": [
    {
      "from": "frontend",
      "to": "backend",
      "variant": "default"
    }
  ]
}

Full-Featured Diagram

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Archify",
    "subtitle": "Agent skill → JSON IR → typed renderers → standalone HTML",
    "output": "examples/archify-repo.html"
  },
  "components": [
    { "id": "user", "type": "external", "label": "You", "sublabel": "NL or Mermaid", "pos": [40, 300], "size": [120, 60] },
    { "id": "agents", "type": "frontend", "label": "Agent Hosts", "sublabel": "Claude · Codex · opencode", "pos": [200, 300], "size": [150, 60] },
    { "id": "ir", "type": "messagebus", "label": "JSON IR", "sublabel": "schema_version: 1", "pos": [400, 300], "size": [140, 60] },
    { "id": "renderers", "type": "backend", "label": "Renderers ×5", "sublabel": "layout checks", "pos": [590, 300], "size": [140, 60] },
    { "id": "html", "type": "cloud", "label": "HTML Artifact", "sublabel": "single file", "pos": [1160, 300], "size": [140, 60] }
  ],
  "boundaries": [
    { "kind": "region", "label": "archify/ skill package", "wraps": ["ir", "schemas", "renderers", "template", "checker"] }
  ],
  "connections": [
    { "from": "user", "to": "agents", "variant": "emphasis" },
    { "from": "agents", "to": "ir", "label": "write IR", "variant": "emphasis" },
    { "from": "ir", "to": "renderers", "variant": "emphasis" },
    { "from": "renderers", "to": "template", "variant": "emphasis" },
    { "from": "template", "to": "checker", "variant": "emphasis" },
    { "from": "checker", "to": "html", "label": "deliver", "variant": "emphasis" }
  ],
  "cards": [
    {
      "dot": "emerald",
      "title": "Render path",
      "items": [
        "JSON IR pins schema_version: 1",
        "Five typed renderers: architecture / workflow / sequence / dataflow / lifecycle",
        "template.html owns theme toggle and 4× export"
      ]
    }
  ]
}

Summary

• Archify uses a JSON IR format validated against architecture.schema.json to render architecture diagrams
• Every diagram requires schema_version: 1, diagram_type: "architecture", a meta object with title, and at least one component
• Components support positioning via pos/size or grid-based row/col placement
• Connections support multiple routing algorithms (straight, orthogonal-h, orthogonal-v, auto) and styling variants
• Boundaries group components visually, while cards add explanatory annotations
• The AJV validator in archify/package.json enforces schema compliance before rendering

Frequently Asked Questions

What is the minimum required JSON to create a valid Archify architecture diagram?

The smallest valid diagram requires four top-level properties: schema_version set to 1, diagram_type set to "architecture", a meta object containing at least a title string, and a components array with at least one component having id, type, and label. Without these, the AJV validator in archify/schemas/architecture.schema.json will reject the input.

Which component types are available in Archify's JSON IR format?

The type field in each component must match an enum defined in archify/schemas/common.schema.json. Valid values are frontend, backend, database, cloud, security, messagebus, and external. Using any other string will fail schema validation.

How do I control the routing of connections between components?

Use the route property in a connection object to specify the path algorithm. Options include auto (default), straight (direct line), orthogonal-h (horizontal-first Manhattan routing), and orthogonal-v (vertical-first Manhattan routing). For custom paths, provide an array of [x, y] coordinates in the via property to force specific waypoints.

Can I link a diagram to a specific GitHub repository commit?

Yes. Add a repository object to your meta section containing url (the repository HTTPS path) and sha (the 40-character commit hash). This creates a permanent reference between your architecture diagram and the codebase state it represents, as demonstrated in the archify-repo.architecture.json example.

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