Layout JSON Output for Archify Architecture Diagrams: Schema, Grid Mode, and Configuration Guide

Archify uses a dedicated layout object with a "grid" mode to automatically position diagram elements, controlled by parameters like origin, cols, gapX, gapY, cellW, and cellH defined in architecture.schema.json.

Archify generates architecture diagrams from structured JSON files, and every diagram supports an optional layout section that eliminates manual coordinate calculations. According to the tt-a1i/archify source code, this object is formally specified in archify/schemas/architecture.schema.json and enables predictable, repeatable placements for complex diagrams such as data pipelines or microservice topologies.

Layout Object Schema and Required Properties

The layout object sits at the top level of any architecture diagram JSON file. The schema mandates a mode property and accepts several optional geometry parameters that define the grid's structure.

Core Properties

Property	Type	Description
mode	string (enum)	Must be "grid" — currently the only supported layout engine.
origin	[x, y] array	Top‑left coordinate of the grid in diagram space.
cols	integer (1–12)	Number of grid columns; defaults to 1 if omitted.
gapX	number ≥ 0	Horizontal spacing between adjacent cells.
gapY	number ≥ 0	Vertical spacing between adjacent cells.
cellW	number ≥ 40	Minimum width of each grid cell.
cellH	number ≥ 24	Minimum height of each grid cell.

The constraints on cellW and cellH ensure that components render with sufficient visual clarity regardless of content density.

Grid Mode: Automatic Positioning with Row/Col Indices

When mode is set to "grid", Archify's renderer calculates component positions automatically. Components reference grid cells using row and col indices instead of absolute coordinates.

This system excels for multi‑lane diagrams where logical flow maps cleanly to grid rows. Consider a deployment pipeline with source, build, test, and deploy stages — each stage occupies a column, and each service tier occupies a row.

Position Override Behavior

A component can still specify a manual pos array ([x, y]) to override grid placement for fine‑grained control. This hybrid approach lets you establish a baseline grid while adjusting critical elements for visual emphasis or connector routing.

Minimal Layout JSON Output Example

The following snippet demonstrates the smallest valid layout configuration:

{
  "layout": {
    "mode": "grid",
    "origin": [40, 100],
    "cols": 7,
    "gapX": 24,
    "gapY": 48,
    "cellW": 120,
    "cellH": 60
  }
}

This defines a 7‑column grid starting at coordinate (40, 100), with 120×60 pixel cells and generous spacing between them.

Complete Architecture Diagram with Layout

The file examples/archify-repo-grid.architecture.json in the Archify repository provides a full implementation. Here is an annotated excerpt showing how layout, components, and connections interact:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Archify Pipeline",
    "subtitle": "Grid placement demo — row/col instead of manual pos",
    "output": "examples/archify-repo-grid.html"
  },
  "layout": {
    "mode": "grid",
    "origin": [40, 100],
    "cols": 7,
    "gapX": 24,
    "gapY": 48,
    "cellW": 120,
    "cellH": 60
  },
  "components": [
    { "id": "user", "type": "external", "label": "You", "row": 1, "col": 0 },
    { "id": "agents", "type": "frontend", "label": "Agent Hosts", "row": 1, "col": 1 },
    { "id": "skill", "type": "frontend", "label": "SKILL.md", "row": 0, "col": 1 }
  ],
  "connections": [
    { "from": "user", "to": "agents", "variant": "emphasis" },
    { "from": "agents", "to": "skill", "fromSide": "top", "toSide": "bottom" }
  ]
}

Notice how components user, agents, and skill use row and col to target specific grid cells, while connections route between them automatically.

Source Files and Validation

Archify enforces the layout schema through two key files:

• archify/schemas/architecture.schema.json — Contains the complete JSON Schema definition, including type constraints, enum values, and numeric ranges for all layout properties.
• examples/archify-repo-grid.architecture.json — A working reference that demonstrates grid layout in a realistic multi‑component diagram.

Any diagram JSON that includes a layout object is validated against this schema before rendering, ensuring that malformed configurations fail fast with descriptive errors.

Summary

• The layout JSON output in Archify centers on a layout object with mode: "grid" as the sole supported engine.
• Seven properties control the grid: mode, origin, cols (1–12), gapX, gapY, cellW (≥40), and cellH (≥24).
• Components use row and col indices for automatic placement, or pos for manual override.
• The schema lives in archify/schemas/architecture.schema.json and is exemplified in examples/archify-repo-grid.architecture.json.

Frequently Asked Questions

What layout modes does Archify support?

Archify currently supports only the "grid" layout mode. The architecture.schema.json file defines this as an enum with a single value, though the schema structure allows for future expansion to additional layout engines.

Can I mix grid placement with manual positioning?

Yes. Components inside a grid‑mode diagram default to automatic placement via row and col, but supplying a pos array overrides this for that specific component. This hybrid approach enables precise adjustments without abandoning the grid system entirely.

What happens if I omit the cols property in my layout JSON?

The architecture.schema.json schema specifies a default value of 1 for cols when omitted. This creates a single‑column vertical stack, which may be useful for simple linear diagrams but typically requires explicit configuration for multi‑column layouts.

Where can I find the complete schema for layout validation?

The authoritative source is archify/schemas/architecture.schema.json in the tt-a1i/archify repository. This file defines all layout properties, their types, constraints, and defaults. The file examples/archify-repo-grid.architecture.json provides a validated, runnable example for reference.

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