# What Is Composition Checking in Archify? Layout Validation for Architecture Diagrams

> Discover composition checking in Archify, the architecture diagram validation tool. Improve clarity by detecting edge crossings and clutter with automated layout checks.

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

---

**Composition checking in Archify is a validation step that analyzes the geometric layout of architecture diagrams to detect visual issues like edge crossings and clutter, assigning a "pass" or "fail" status based on configurable thresholds.**

The **tt-a1i/archify** repository includes a composition validator that automatically inspects every generated diagram. This process ensures that architecture visualizations maintain readability standards by checking for geometric anti-patterns before they reach production. Composition checking evaluates spatial relationships between frames and edges, returning a structured report within the artifact receipt.

## How Composition Checking Works

When Archify generates a diagram, the composition validator evaluates the spatial arrangement of elements. It calculates specific geometric metrics to quantify visual clarity and stores the results in a `validation.composition` object.

### Core Composition Metrics

The validator tracks six key indicators of diagram quality:

- **properCrossings**: Counts edge-to-edge intersections that should be avoided for readability.
- **containerBorderRuns**: Measures how many times a frame's border is broken by interior elements.
- **microSegmentCount**: Tallies short line segments that cause visual clutter.
- **shortInteriorSegmentCount**: Counts interior line segments that are unusually short, often indicating cramped turns.
- **compositionProfile**: A named profile (e.g., "showcase") that groups threshold settings for the above metrics.
- **compositionStatus**: The final verdict, returning `"pass"` if all metrics are within acceptable thresholds, otherwise `"fail"`.

### Validation Profiles

Each diagram is evaluated against a specific **composition profile** that defines acceptable thresholds. The "showcase" profile represents a strict preset designed for publication-ready diagrams, ensuring minimal crossings and clean geometry.

## Running Composition Checks in the Archify CLI

The validator executes automatically during several CLI workflows, printing human-readable summaries or structured JSON receipts.

### Preview Command Validation

To validate a single diagram and view the composition status:

```bash
npx archify preview path/to/architecture.json

```

A successful check produces output like:

```

✔ 1/1 artifact checks; composition SHOWCASE: PASS

```

If metrics exceed thresholds, the status changes to `FAIL`:

```

✖ 1/1 artifact checks; composition SHOWCASE: FAIL

```

### Extracting Detailed Metrics

To inspect the raw composition data programmatically, use the `--json` flag:

```bash
npx archify preview --json path/to/architecture.json | jq '.validation.composition'

```

This outputs the validation object:

```json
{
  "properCrossings": 0,
  "containerBorderRuns": 1,
  "microSegmentCount": 3,
  "shortInteriorSegmentCount": 0,
  "profile": "showcase",
  "status": "pass"
}

```

### Gallery Validation

During bulk operations, `archify build-gallery` renders a gallery of artifacts. As implemented in `scripts/build-gallery.mjs` (lines 225-320), this command displays composition status badges for each diagram, enabling quick identification of layout failures across multiple files.

## Source Code Implementation

The composition checking system spans the CLI entry point, receipt generation, and test suite.

### CLI Receipt Processing

In `archify/bin/archify.mjs` at line 1022, the CLI extracts `compositionStatus` from the artifact receipt. It formats the human-readable summary displayed in terminal output, parsing the `validation.composition` object to render the pass/fail indicators.

### Gallery Badge Generation

The gallery builder in `scripts/build-gallery.mjs` processes composition data to generate visual badges. Between lines 225 and 320, the script reads each artifact's validation metadata and renders composition profiles alongside pass/fail status indicators, making diagnostic information accessible in bulk renders.

### Test Coverage

The validation logic is enforced by tests in `archify/test/preview.test.mjs` at line 232. The test suite asserts that successful preview operations return `compositionStatus: 'pass'`, ensuring that regressions in layout validation trigger build failures.

### Receipt Generation

The underlying geometric calculations occur during the preview phase. The `archify/bin/preview.mjs` module generates the artifact receipt, populating the `validation.composition` object with calculated metrics before Archify finalizes the output file.

## Summary

- Composition checking in Archify validates diagram geometry against readability standards.
- Six metrics—including proper crossings, border runs, and micro-segments—determine visual quality.
- The validator returns both a binary status and detailed JSON reports via the artifact receipt.
- Checks run automatically during `archify preview` and `archify build-gallery` operations.
- Implementation spans `archify.mjs`, `build-gallery.mjs`, `preview.mjs`, and associated test files.

## Frequently Asked Questions

### What triggers a composition check to fail?

A composition check fails when any metric exceeds its threshold for the active profile. For example, excessive proper crossings or a high micro-segment count will set `compositionStatus` to `"fail"` and expose the offending metrics in the validation receipt, allowing developers to identify specific layout problems.

### How do I view detailed composition metrics?

Run `npx archify preview --json` followed by your diagram path and pipe the output through a JSON processor like `jq` to extract the `.validation.composition` object. This reveals exact counts for crossings, border runs, and segment lengths associated with your architecture.

### Is composition checking mandatory in Archify?

Based on the source analysis, composition checking appears to be a mandatory quality gate. The test suite in `archify/test/preview.test.mjs` explicitly asserts that previews must return `compositionStatus: 'pass'`, and the CLI displays validation results for every artifact without documented opt-out flags.

### What is the "showcase" composition profile?

The "showcase" profile is a strict validation preset designed for publication-ready diagrams. As shown in the CLI output and JSON receipts, this profile enforces tight thresholds on geometric metrics to ensure diagrams meet high readability standards suitable for documentation and presentations.