Archify Diagram Layout Modes: Grid vs. Free Configuration Guide

Archify supports two layout modes for diagram rendering: grid for structured rectangular placement and free for automatic element positioning.

In the tt-a1i/archify repository, diagram layouts are controlled through the renderArchitecture() function in archify/renderers/architecture/render-architecture.mjs. The layout object passed to this function determines how diagram elements are spatially arranged.

Grid Layout Mode

The grid layout mode places diagram elements on a regular, rectangular grid. This mode provides precise control over positioning through configurable parameters.

Grid Configuration Options

In archify/renderers/architecture/render-architecture.mjs at line 624, the grid mode accepts these properties:

• origin: Starting coordinates as [x, y] array
• gapX: Horizontal spacing between cells
• gapY: Vertical spacing between cells
• cellW: Width of each grid cell
• cellH: Height of each grid cell
• cols: Optional number of columns

// Grid layout with full configuration
const diagram = renderArchitecture({
  layout: {
    mode: 'grid',
    origin: [40, 80],
    gapX: 30,
    gapY: 40,
    cellW: 130,
    cellH: 64,
    cols: 4
  }
});

The grid algorithm itself is implemented in archify/renderers/architecture/grid.mjs, while test coverage appears in archify/test/grid.test.mjs to verify correct node placement.

Free Layout Mode

The free layout mode enables automatic element positioning without fixed rows or columns. When no explicit grid configuration is provided, the renderer defaults to this mode.

// Free-form layout (explicit or default)
const diagram = renderArchitecture({
  layout: { mode: 'free' }
});

According to the source in render-architecture.mjs, the renderer returns { mode: 'free' } as the fallback when grid parameters are absent.

How Layout Mode Selection Works

The renderArchitecture() entry point evaluates the layout object to determine which rendering path to execute:

1. If layout.mode === 'grid' with valid grid parameters → apply grid algorithm
2. Otherwise → return free-mode configuration

This branching occurs at the same location (line 624) where both modes are defined, making the selection logic straightforward to trace in the codebase.

Summary

• Two layout modes exist in Archify: grid and free
• grid requires explicit configuration via origin, gapX, gapY, cellW, cellH, and optional cols
• free serves as the automatic fallback when no grid is specified
• Source files: render-architecture.mjs (selection logic), grid.mjs (algorithm), grid.test.mjs (verification)

Frequently Asked Questions

What is the default layout mode in Archify?

The default layout mode when no configuration is provided is free. The renderer automatically returns { mode: 'free' } if the layout object lacks grid-specific parameters or explicitly sets mode: 'free'.

Can I use grid layout without specifying all parameters?

No. The grid mode requires complete configuration including origin, gapX, gapY, cellW, and cellH. The cols parameter is optional. Omitting required grid properties causes the renderer to fall back to free mode.

Where is the grid layout algorithm implemented?

The grid layout algorithm resides in archify/renderers/architecture/grid.mjs. The selection between grid and free modes occurs in archify/renderers/architecture/render-architecture.mjs at line 624.

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