# Archify Diagram Layout Modes: Grid vs. Free Configuration Guide

> Discover Archify diagram layout modes: grid for structured placement and free for automatic positioning. Learn how to best use each mode in this comprehensive guide.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-31

---

**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

```javascript
// 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.

```javascript
// 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.