How the archify inspect Command Outputs Computed Layout JSON

The archify inspect command delegates to the validate command with the --layout-json flag, causing the renderer to compute the full diagram layout and serialize component boxes, boundary boxes, and connection paths into a compact JSON document that is written directly to STDOUT.

The archify inspect command provides a window into the internal layout engine of the tt-a1i/archify tool, exposing exactly how components, boundaries, and connections are positioned on the grid. Unlike the standard validate command that produces visual output, inspect generates machine-readable JSON describing the computed geometry. Understanding this output format is critical for debugging complex architectures, creating custom visualizations, or integrating archify with downstream automation pipelines.

CLI Entry Point: Delegating to validate with --layout-json

In archify/bin/archify.mjs, the inspect subcommand is implemented as a thin wrapper around the existing validation logic. Lines 54-56 map the inspect command directly to commandValidate with the additional --layout-json argument:

case 'inspect':
  commandValidate([...args, '--layout-json']);

This delegation pattern ensures that inspect inherits all the input validation and renderer selection logic from the validate command while adding the special flag that triggers JSON output mode.

Renderer Execution and Layout Computation

The commandValidate function constructs a Node.js subprocess call that executes the appropriate renderer binary. As implemented in the archify source code, the function builds an argument array that includes the input file, a null output path, and the critical --layout-json flag:

const result = runNode([renderer, input, '/dev/null', '--layout-json'], { stdio: 'pipe' });

The renderer—such as archify/renderers/architecture/render-architecture.mjs—performs the actual layout algorithm including grid placement, component sizing, and connection routing. Once the layout is computed, the renderer imports shared serialization helpers from the layout-report module to transform internal objects into JSON-serializable structures.

Serializing Layout Elements with layout-report.mjs

The file archify/renderers/shared/layout-report.mjs provides three essential helper functions that convert the renderer's internal layout objects into standardized JSON format. Each helper rounds numeric coordinates and assigns semantic properties.

Component Box Serialization

The componentBox helper extracts geometric data from diagram components:

import { componentBox, boundaryBox, connectionPath } from '../shared/layout-report.mjs';

const layout = {
  components: diagram.components.map(componentBox),
  // ...
};

Each component entry includes id, type, label, x, y, width, height, and optional grid coordinates (row, col).

Boundary Box Serialization

The boundaryBox helper handles architectural boundaries and groups:

boundaries: diagram.boundaries.map(boundaryBox),

This produces objects containing kind, label, x, y, width, height, and a wraps array listing the contained component IDs.

Connection Path Serialization

The connectionPath helper accepts the connection object, routed path data, and label position:

connections: diagram.connections.map(conn => connectionPath(conn, routed, labelAt)),

Output includes from, to, label, variant, route strategy, an array of points defining the path, and optional labelAt coordinates.

Output Structure and STDOUT Streaming

After constructing the layout object, the renderer streams the JSON directly to standard output using console.log(JSON.stringify(layout, null, 2)). The commandValidate function captures this output through the piped stdio configuration and writes result.stdout unchanged to the terminal (lines 193-199), ensuring no additional formatting or stderr interference occurs during successful execution.

The resulting JSON schema contains three top-level arrays:

{
  "components": [
    {
      "id": "frontend",
      "type": "service",
      "label": "Frontend",
      "x": 120,
      "y": 80,
      "width": 200,
      "height": 100,
      "row": 1,
      "col": 2
    }
  ],
  "boundaries": [
    {
      "kind": "group",
      "label": "Backend",
      "x": 350,
      "y": 70,
      "width": 420,
      "height": 300,
      "wraps": ["api", "db"]
    }
  ],
  "connections": [
    {
      "from": "frontend",
      "to": "api",
      "label": null,
      "variant": "default",
      "route": "auto",
      "points": [[120, 150], [350, 150]]
    }
  ]
}

Practical Usage Examples

To generate layout JSON for debugging or integration:

# Basic inspection output to terminal

archify inspect architecture path/to/my.architecture.json

# Capture to file for further processing

archify inspect architecture path/to/my.architecture.json > layout.json

# Pipe to jq for filtering specific components

archify inspect architecture path/to/my.architecture.json | jq '.components[] | select(.type=="service")'

The command accepts any diagram type supported by archify and validates the input against archify/schemas/architecture.schema.json before computing the layout.

Summary

• The archify inspect command delegates to commandValidate with the --layout-json flag, as defined in archify/bin/archify.mjs (lines 54-56).
• The renderer subprocess receives /dev/null as its output target and --layout-json as a directive to emit JSON instead of images.
• Layout computation occurs in type-specific renderers (e.g., render-architecture.mjs), which use helpers from archify/renderers/shared/layout-report.mjs to serialize data.
• The JSON output includes three main sections: components (with coordinates and grid positions), boundaries (with containment arrays), and connections (with routing points).
• The final JSON is written directly to STDOUT, making it suitable for piping into files (> layout.json) or processing tools like jq.

Frequently Asked Questions

What is the difference between archify inspect and archify validate?

According to the tt-a1i/archify source code, archify inspect is essentially an alias that invokes archify validate with the --layout-json flag automatically appended. While validate typically produces rendered output or validation errors, inspect forces the renderer to emit the computed layout as JSON to STDOUT, exposing the internal grid coordinates and connection paths.

Why does the inspect command use /dev/null as an output path?

The /dev/null argument in the runNode call satisfies the renderer's expected argument signature without creating an actual output file. Since the --layout-json flag causes the renderer to write layout data to STDOUT instead of generating a diagram file, the null device serves as a placeholder destination that gets ignored during JSON serialization mode.

How are coordinate values handled in the layout JSON?

The layout-report.mjs helpers round numeric values to integers before serialization to ensure clean JSON output and deterministic diffs. Component boxes include absolute pixel coordinates (x, y) plus optional grid positions (row, col), while connection paths store rounded point arrays that define the routing geometry between elements.

Can I use the inspect output with external visualization tools?

Yes, the JSON structure emitted by archify inspect follows a predictable schema containing standardized geometry for components, boundaries, and connections. You can pipe this output directly into custom rendering pipelines, import it into data visualization tools like D3.js, or validate it against the layout schema for integration with automated documentation systems.

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