Archify JSON IR Structure for Different Diagram Types: Complete Schema Reference

Archify represents every diagram as a JSON intermediate representation (IR) that combines common top-level fields—schema_version, diagram_type, and meta—with domain-specific structures defined in separate JSON Schema files for architecture, workflow, sequence, lifecycle, and dataflow diagrams.

Archify is an open-source diagramming engine that renders production-ready SVG and HTML visuals from declarative JSON input. Mastering the JSON IR structure for different diagram types enables developers to programmatically generate complex architectural blueprints, swim-lane workflows, and UML sequence diagrams. Each schema is strictly validated against official JSON Schema definitions stored in the repository's archify/schemas/ directory.

Architecture Diagram IR Structure

The architecture diagram schema supports grid-based system architecture visualizations. According to archify/schemas/architecture.schema.json, the IR requires a grid layout mode and defines three primary entity arrays.

Core fields:

• layout – Currently supports only "mode": "grid" with cols, cellW, cellH, and spacing parameters.
• components – Building blocks such as servers or databases with id, type, label, and optional grid coordinates (row, col) or absolute pos.
• boundaries – Grouping containers with kind (region or security-group) and a wraps array listing enclosed component IDs.
• connections – Directed edges between components specifying from, to, and visual variant (emphasis, security, dashed).

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Simple Web Stack" },
  "layout": { "mode": "grid", "cols": 6, "cellW": 120, "cellH": 80 },
  "components": [
    { "id": "users", "type": "frontend", "label": "Users", "row": 0, "col": 0 },
    { "id": "cdn", "type": "cloud", "label": "CDN", "row": 0, "col": 1 },
    { "id": "api", "type": "backend", "label": "API Server", "row": 0, "col": 3 },
    { "id": "db", "type": "database", "label": "PostgreSQL", "row": 0, "col": 4 }
  ],
  "connections": [
    { "from": "users", "to": "cdn", "variant": "emphasis" },
    { "from": "cdn", "to": "api", "variant": "emphasis" }
  ]
}

See the full schema at [archify/schemas/architecture.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) and a production example at [archify/examples/web-app.architecture.json](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json).

Workflow Diagram IR Structure

Workflow diagrams use a swim-lane (lane-based) layout defined in archify/schemas/workflow.schema.json. The IR separates vertical responsibility lanes from horizontal phase bands.

Key constructs:

• lanes – Vertical swim-lanes (e.g., UI, Agent, Policy) identified by id and label.
• phases – Optional horizontal bands grouping columns with fromCol, toCol, and visual variant.
• groups – Rectangular blocks spanning a specific lane and column range for visual nesting.
• nodes – Symbols placed at a specific lane and col coordinate with a defined type.
• edges – Connections featuring a role property (main, branch, async, return, error) and route hints (auto, drop, outside-right).

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Simple Agent Flow" },
  "lanes": [
    { "id": "ui", "label": "User Interface" },
    { "id": "agent", "label": "Agent Runtime" }
  ],
  "nodes": [
    { "id": "req", "lane": "ui", "col": 0, "type": "frontend", "label": "Request" },
    { "id": "plan", "lane": "agent", "col": 1, "type": "backend", "label": "Planner" },
    { "id": "exec", "lane": "agent", "col": 2, "type": "backend", "label": "Execute" }
  ],
  "edges": [
    { "from": "req", "to": "plan", "role": "main", "variant": "emphasis" },
    { "from": "plan", "to": "exec", "role": "main", "variant": "emphasis" }
  ]
}

Reference the schema at [archify/schemas/workflow.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) and the multi-step agent example at [archify/examples/agent-tool-call.workflow.json](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json).

Sequence Diagram IR Structure

The sequence diagram IR in archify/schemas/sequence.schema.json models temporal interactions between vertical participants using lifelines and horizontal messages.

Structural elements:

• participants – Vertical lifelines categorized by type (frontend, backend, database, messagebus, external).
• messages – Horizontal arrows with from and to participant IDs, segment grouping, and boolean activation to render activation bars.
• segments – Logical phases (e.g., Auth, Cache) that group related messages.
• variant – Visual styles including emphasis, security, dashed, or return.

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": { "title": "Cache Miss Flow" },
  "participants": [
    { "id": "client", "type": "frontend", "label": "Client" },
    { "id": "api", "type": "backend", "label": "API Server" },
    { "id": "redis", "type": "database", "label": "Redis" }
  ],
  "messages": [
    { "id": "m1", "from": "client", "to": "api", "label": "GET /dashboard", "variant": "emphasis", "segment": 0, "activation": true },
    { "id": "m2", "from": "api", "to": "redis", "label": "READ", "variant": "default", "segment": 1, "activation": true },
    { "id": "m3", "from": "redis", "to": "api", "label": "MISS", "variant": "return", "segment": 1 }
  ]
}

Validate against [archify/schemas/sequence.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) and study the request-flow example at [docs/gallery/sources/cache-miss-request.sequence.json](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/cache-miss-request.sequence.json).

Lifecycle Diagram IR Structure

Lifecycle diagrams visualize state machines with horizontal lanes separating active states from interruptions and terminal exits. The schema is defined in archify/schemas/lifecycle.schema.json.

Domain-specific fields:

• lanes – Horizontal bands such as main, waiting, exceptions, and terminal, each with a variant (normal or exception).
• states – Nodes positioned in a specific lane at a col index.
• transitions – Directed edges with variant styling (emphasis, security, dashed) and explicit route control (auto, straight, orthogonal).

{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Job Lifecycle" },
  "lanes": [
    { "id": "main", "label": "Active" },
    { "id": "interrupt", "label": "Interrupt", "variant": "exception" },
    { "id": "terminal", "label": "Exit", "variant": "exception" }
  ],
  "states": [
    { "id": "queued", "lane": "main", "label": "Queued", "col": 0 },
    { "id": "running", "lane": "main", "label": "Running", "col": 1 },
    { "id": "paused", "lane": "interrupt", "label": "Paused", "col": 1 },
    { "id": "cancelled", "lane": "terminal", "label": "Cancelled", "col": 2 }
  ],
  "transitions": [
    { "from": "queued", "to": "running", "variant": "emphasis" },
    { "from": "running", "to": "paused", "variant": "security" },
    { "from": "paused", "to": "running", "variant": "emphasis" }
  ]
}

Consult [archify/schemas/lifecycle.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) and the agent execution example at [docs/gallery/sources/agent-run.lifecycle.json](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/agent-run.lifecycle.json).

Data-Flow Diagram IR Structure

Data-flow diagrams use a simplified IR defined in archify/schemas/dataflow.schema.json. Unlike architecture diagrams, this format omits explicit layout hints and grid coordinates; the visual layout is inferred from the preset configuration.

Minimal structure:

• components – Standard entity definitions with id, type, and label.
• connections – Directed flows with optional text label and variant styling.

{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": { "title": "Analytics Pipeline" },
  "components": [
    { "id": "web", "type": "frontend", "label": "Web SDK" },
    { "id": "edge", "type": "backend", "label": "Edge API" },
    { "id": "store", "type": "database", "label": "Warehouse" }
  ],
  "connections": [
    { "from": "web", "to": "edge", "variant": "emphasis", "label": "events" },
    { "from": "edge", "to": "store", "variant": "emphasis", "label": "ingest" }
  ]
}

Review the full specification at [archify/schemas/dataflow.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) and the analytics example at [docs/gallery/sources/product-analytics.dataflow.json](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/product-analytics.dataflow.json).

Summary

The Archify JSON IR structure provides a type-safe, schema-validated foundation for five distinct diagram categories:

• Architecture diagrams rely on grid-based layout with explicit components, boundaries, and connections.
• Workflow diagrams organize logic into vertical lanes, horizontal phases, and semantic edges with role-based routing.
• Sequence diagrams model time-series interactions through participants, messages, grouped segments, and activation bars.
• Lifecycle diagrams separate states into semantic horizontal lanes (main, interrupt, terminal) with explicit transitions.
• Data-flow diagrams offer a simplified component-connection model without manual layout coordinates.

Frequently Asked Questions

What fields are common to all Archify JSON IR structures?

Every diagram IR must include schema_version (integer), diagram_type (string), and meta (object). The meta object typically contains title, optional subtitle, locale, viewBox, and rendering hints like visual preset and quality profile. All schemas also support an optional cards object for metadata attachments.

How does the Workflow diagram IR differ from Architecture diagrams?

Workflow IR uses lanes and nodes positioned by column index rather than explicit grid coordinates, and it introduces semantic edges with role properties (main, branch, async, return, error). Architecture diagrams instead use absolute or grid-relative positioning with row and col fields, and organize components into boundaries rather than swim-lanes.

Can I define custom routing for connections in the JSON IR?

Yes. The workflow, lifecycle, and architecture schemas accept a route property on connections or edges. Valid values include "auto", "straight", "orthogonal", "drop", and "outside-right". If omitted, the renderer applies automatic pathfinding based on the diagram type's layout algorithm.

Where can I find the official JSON Schema definitions for validation?

All schemas reside in the archify/schemas/ directory: architecture.schema.json, workflow.schema.json, sequence.schema.json, lifecycle.schema.json, and dataflow.schema.json. Production-ready examples are located in archify/examples/ and docs/gallery/sources/, providing validated templates for each diagram type.

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