Grid Layout System for Archify Architecture Diagrams: JSON Configuration and Position Resolution

Archify’s grid layout system maps architecture components to fixed cell positions using row and column indices, calculating pixel coordinates through deterministic arithmetic defined in grid.mjs while allowing absolute coordinate overrides.

Archify is an open-source diagramming tool that renders architecture diagrams from JSON-encoded intermediate representations (IR). When you set "mode": "grid" in your diagram’s top-level layout object, the grid layout system for Archify architecture diagrams activates deterministic placement based on configurable cell parameters rather than free-hand coordinates.

How the Grid Layout System Works in Archify

The grid layout processes your architecture IR through three distinct phases: parameter merging, position resolution, and validation. This pipeline ensures reproducible diagrams while maintaining strict constraints on component placement.

Default Grid Parameters in grid.mjs

When your diagram does not specify custom grid values, Archify imports preset defaults from archify/renderers/architecture/grid.mjs:

{
  mode: 'grid',
  origin: [40, 80],
  cols:   4,
  gapX:   30,
  gapY:   40,
  cellW:  130,
  cellH:  64
}

These defaults establish the coordinate system origin at (40, 80), define a four-column grid, and set uniform gaps between cells. Every grid diagram starts from this baseline unless explicitly overridden.

Merging User Configuration

The gridLayout(arch) function (lines 13–17 in grid.mjs) performs a shallow merge between the preset defaults and any user-supplied layout properties. If layout.mode is not "grid", the function returns null, signaling the renderer to use free-form positioning instead.

Position Resolution and Validation

Each component in your architecture can specify placement via either row/col indices or absolute [x, y] coordinates. The resolveComponentPos(component, grid) function (lines 27–31) translates grid indices to pixel coordinates using the formula:

x = originX + col * (cellW + gapX)
y = originY + row * (cellH + gapY)

Before rendering, validateGridPlacement (lines 33–61) enforces four critical constraints:

• Every component must have either a pos array or valid row/col values
• Row and column indices must be non-negative integers
• Column values cannot exceed the grid.cols limit
• No two components may occupy the identical cell

Validation errors accumulate in a problems array that the CLI surfaces to the user.

Positioning Components Using Row and Column Indices

To place components using the grid system, assign row and col properties in your JSON definition. This example from examples/archify-repo-grid.architecture.json demonstrates a multi-column layout:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "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": "Agents", "row": 1, "col": 1 },
    { "id": "skill",  "type": "frontend", "label": "SKILL",  "row": 0, "col": 1 }
  ]
}

After processing, the CLI generates an SVG where the background shows the grid pattern and components align to their specified cells (as verified in archify/test/cli.test.mjs, lines 161–167).

Absolute Position Overrides

You can override grid calculations for individual components by providing a pos array. When resolveComponentPos detects a pos property, it returns those coordinates directly, bypassing the row/cell arithmetic:

{
  "components": [
    {
      "id": "skill",
      "type": "frontend",
      "label": "SKILL",
      "row": 0,
      "col": 1,
      "pos": [300, 180]
    }
  ]
}

This technique allows fine-tuned adjustments without abandoning the grid system entirely.

Configuring the Grid in Your Architecture Diagram

The layout object in your IR supports six grid-specific properties:

• origin: [x, y] array defining the top-left coordinate of the grid
• cols: Integer specifying the maximum number of columns
• cellW: Width of each grid cell in pixels
• cellH: Height of each grid cell in pixels
• gapX: Horizontal spacing between columns
• gapY: Vertical spacing between rows

When the diagram reaches the final rendering stage in render-architecture.mjs (line 220), the top-level layout object is stored as:

layout: grid ? { mode: 'grid', ...grid } : { mode: 'free' }

This structure signals downstream renderers to apply grid-based clipping and background pattern generation.

Programmatic Access to Grid Calculations

You can import the grid utilities directly from grid.mjs to preview positions or build custom tooling:

import { gridLayout, resolveComponentPos } from './archify/renderers/architecture/grid.mjs';
import arch from './my-diagram.architecture.json' assert { type: 'json' };

const grid = gridLayout(arch);
if (grid) {
  arch.components.forEach(comp => {
    const [x, y] = resolveComponentPos(comp, grid);
    console.log(`${comp.id}: (${x}, ${y})`);
  });
}

This script outputs the exact pixel coordinates that Archify will use during SVG generation, enabling you to verify placement before rendering.

Summary

• Archify activates grid layout when layout.mode is set to "grid" in your architecture diagram JSON.
• Default parameters in grid.mjs provide a 4-column baseline with predefined cell dimensions and gaps.
• The gridLayout function merges user settings with defaults, while resolveComponentPos converts row/col indices to pixel coordinates using deterministic arithmetic.
• validateGridPlacement enforces non-negative indices, column limits, and prevents duplicate cell occupancy before rendering occurs.
• Components can override grid calculations by specifying a pos array for fine-tuned positioning.
• The final layout object stored in render-architecture.mjs (line 220) informs downstream renderers to generate grid backgrounds and cell-aligned SVG elements.

Frequently Asked Questions

How do I enable grid layout in Archify architecture diagrams?

Set "mode": "grid" inside the top-level layout object of your JSON intermediate representation. You can optionally provide origin, cols, cellW, cellH, gapX, and gapY values to customize the grid; otherwise, Archify uses the defaults defined in grid.mjs.

Can I mix grid-based positioning with absolute coordinates?

Yes. The resolveComponentPos function checks for a pos property before calculating grid coordinates. If pos exists as an [x, y] array, those values override the computed grid position, allowing precise adjustments for individual components while maintaining the grid structure for others.

What are the default grid parameters in Archify?

The fallback configuration in archify/renderers/architecture/grid.mjs sets origin to [40, 80], cols to 4, gapX to 30, gapY to 40, cellW to 130, and cellH to 64. These values determine a compact, four-column layout unless your JSON explicitly overrides them.

How does Archify validate grid placement?

The validateGridPlacement function (lines 33–61 in grid.mjs) verifies that all components have valid positioning data, ensures row and col values are non-negative integers within the column limit, and detects duplicate cell occupancy. Any violations are collected in a problems array that the CLI reports before rendering fails.

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