How to Use Layout JSON Output for Debugging Archify Diagrams

Archify's layout JSON output captures the exact coordinates, grid positions, and sizing data for every diagram component, enabling precise debugging of visual placement through direct data inspection and manual coordinate adjustment.

Archify's diagram engine maintains a strict separation between structure (nodes, edges, and lanes) and layout (computed positions and dimensions). When rendering, the engine can emit a layout JSON file that records the precise geometry assigned to each component. Mastering how to use this layout JSON output for debugging Archify diagrams transforms vague visual complaints into specific, actionable data corrections.

Understanding the Layout JSON Structure

The layout object resides under the top-level layout key in an Archify architecture file. According to the source code in archify/schemas/architecture.schema.json at line 68, the schema defines layout as an optional object containing specific geometric properties that vary by rendering mode.

Schema Definition and Properties

The schema at archify/schemas/architecture.schema.json specifies the following layout properties:

Property	Type	Description
mode	string	Either "grid" or "free" – selects the layout algorithm.
row / col	integer	Grid coordinates for components (used when mode is "grid").
x, y, width, height	number	Absolute pixel values (used when mode is "free").
viewBox	array	Overall canvas dimensions [width, height] for viewport verification.

Layout Modes and Coordinates

Grid mode assigns components to specific row and column indices, making it ideal for structured diagrams like swimlanes or matrices. Free mode uses absolute pixel coordinates (x, y) and explicit dimensions, offering precise control over component placement but requiring manual collision avoidance.

Debugging Workflow with Layout JSON

A systematic approach to debugging diagram rendering involves generating the layout JSON, inspecting the computed values, and iteratively adjusting coordinates until the visual output matches expectations.

Generating the Output

Use the --layout-output flag when rendering to extract the computed geometry into a separate JSON file:

archify render \
  --input examples/archify-repo-grid.architecture.json \
  --output dist/archify-repo-grid.html \
  --layout-output dist/archify-repo-grid.layout.json

This creates a machine-readable record of every component's position that you can examine independently of the visual renderer.

Inspecting Component Geometry

Open the generated JSON to locate specific components by their id and verify their assigned coordinates. A typical layout JSON structure appears as follows:

{
  "layout": {
    "mode": "grid",
    "components": [
      { "id": "skill", "row": 0, "col": 1 },
      { "id": "frontend", "row": 0, "col": 2 },
      { "id": "backend", "row": 1, "col": 2 }
    ],
    "viewBox": [1200, 800]
  }
}

Cross-reference these values with the rendered SVG or HTML output. If the backend node appears in the wrong column, check whether col matches your expectation or if an automatic layout algorithm shifted it due to constraint violations.

Manual Adjustment and Re-rendering

For diagrams requiring pixel-perfect placement, edit the layout JSON directly and feed it back into the renderer using the --layout-input flag. This workflow allows deterministic control without modifying the original architecture file:

# Move the "backend" component one column to the right

jq '.layout.components[] |= if .id=="backend" then .col+=1 else . end' \
    dist/archify-repo-grid.layout.json > temp.layout.json

# Re-render using the edited layout

archify render \
  --input examples/archify-repo-grid.architecture.json \
  --layout-input temp.layout.json \
  --output dist/archify-repo-grid-fixed.html

This approach is particularly effective for resolving edge overlaps, label truncations, or lane alignment issues in grid-based diagrams.

Validating Layout Constraints

The layout JSON serves as input for Archify's built-in validator, which checks against structural limits defined in the schema. Run the validator to catch spacing violations, out-of-bounds components, or invalid coordinate combinations:

archify validate examples/archify-repo-grid.architecture.json

The validator references the same schema at archify/schemas/architecture.schema.json to enforce limits on label widths, node-lane bounds, and edge spacing. Using the layout JSON as a debugging artifact, you can identify whether rendering errors stem from constraint violations or algorithmic miscalculations.

Automating Regression Testing

Store canonical layout JSON files alongside your architecture definitions to detect unintended layout drift. When automatic layout algorithms update or when editing complex diagrams, compare the newly generated layout JSON against the stored baseline:

1. Generate the layout JSON during CI builds.
2. Diff against the canonical version.
3. Flag any coordinate changes for manual review.

This practice turns visual layout debugging into a repeatable, source-controlled process that catches pixel shifts before they reach production documentation.

Summary

• Archify emits layout JSON via the --layout-output flag, recording exact row, col, x, y, width, and height values for every component.
• The schema at archify/schemas/architecture.schema.json (line 68) defines the layout object structure, supporting both "grid" and "free" positioning modes.
• Debug by inspection: Cross-reference JSON coordinates with rendered output to diagnose misplaced nodes or edge crossings.
• Manual iteration: Edit coordinates in the JSON and re-render using --layout-input for deterministic placement without rewriting architecture files.
• Validation: Use archify validate to check layout constraints against the schema before finalizing diagrams.

Frequently Asked Questions

How do I generate a layout JSON file from an Archify diagram?

Run the archify render command with the --layout-output parameter followed by your desired file path. This flag instructs the renderer to write the computed geometry—including all coordinates, dimensions, and viewBox data—to a separate JSON file while still generating the visual output.

What is the difference between grid and free layout modes in Archify?

Grid mode assigns components to specific row and col indices, creating structured alignments suitable for matrices or swimlanes. Free mode uses absolute pixel coordinates (x, y) and explicit width and height values, providing precise control over positioning but requiring manual management of spacing and overlap prevention.

Can I manually edit the layout JSON to fix component positions?

Yes. The layout JSON is pure data that you can modify with any text editor or JSON manipulation tool like jq. After editing coordinates, pass the modified file to archify render using the --layout-input flag to generate updated visual output without altering the original architecture definition.

How does the layout JSON help validate diagram constraints?

The layout JSON contains the actual computed values that the renderer used, allowing you to verify against the schema limits defined in archify/schemas/architecture.schema.json. By running archify validate against your architecture file, you ensure that no components exceed lane bounds, violate minimum spacing requirements, or break label width constraints recorded in the layout data.

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