# How the archify inspect Command Outputs Computed Layout JSON

> Learn how the archify inspect command outputs computed layout JSON. Discover how it generates a compact JSON document detailing component boxes, boundaries, and connection paths directly to STDOUT.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-07-14

---

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

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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:

```json
{
  "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:

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/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.