# Archify Visual Quality Composition Checks: 4 Metrics That Guarantee Diagram Quality

> Discover Archify's 4 visual quality composition checks: proper crossings, container border runs, micro-segments, and short interior segments. Ensure diagram quality with Archify's metrics.

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

---

**Archify validates every generated diagram with four deterministic geometric checks: proper crossings, container border runs, micro‑segments, and short interior segments.** The tool reports these as concrete metrics and fails the build if any threshold is exceeded.

All visual‑quality composition checks in **Archify** run through a deterministic validator that examines the geometric structure of each diagram before acceptance. The system is designed to catch readability issues that automated layout algorithms often introduce. This article explains the four metrics, their implementation in the source code, and how to run these checks from the CLI or test suite.

## The Four Composition Check Metrics

The validator inspects every diagram for four specific geometric problems. Each metric targets a distinct category of visual noise that degrades diagram clarity.

### Proper Crossings (properCrossings)

A **proper crossing** occurs when two non‑adjacent edges intersect at a point that is not a node. The `properCrossings` metric counts these intersections.

Fewer crossings improve readability. A value ≥ 1 indicates "crossing debt" that the layout engine should resolve. The test suite explicitly asserts zero crossing debt for gallery entries in [`archify/test/gallery.test.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/test/gallery.test.mjs).

### Container Border Runs (containerBorderRuns)

This metric counts how often an edge runs along the border of a structural frame—such as a region, lane, or security group.

Excessive border runs create visual clutter and obscure hierarchical relationships. Low values preserve clear framing and keep attention on the topology rather than the container geometry.

### Micro‑Segment Count (microSegmentCount)

**Micro‑segments** are tiny line fragments ≤ 2 px that appear inside nodes or frames. These are typically artifacts of layout algorithms or rounding errors.

High micro‑segment counts make diagrams look noisy and unpolished. The validator flags these for elimination during refinement passes.

### Short Interior Segment Count (shortInteriorSegmentCount)

This counts short edge segments that make sharp turns inside a frame—also called **cramped turns**. These turns disrupt the visual flow of edges through containers.

Smooth paths require fewer sharp angles. Reducing cramped turns yields diagrams where edge routing is immediately interpretable.

## Running Composition Checks

Archify exposes the composition validator through the CLI, programmatic API, and test suite. All three interfaces use the same underlying implementation and report identical metrics.

### CLI Validation with Quality Profiles

The `preview` command accepts a `--quality` flag to enforce the **showcase** profile, which includes composition checks.

```bash

# Render and validate a diagram with showcase quality requirements

node archify/bin/archify.mjs preview architecture examples/web-app.json \
  /tmp/web-app.html --quality showcase

```

Output includes a composition status line:

```

… 1/1 artifact checks; composition SHOWCASE: PASS; …

```

The CLI entry point in [`archify/bin/archify.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs) aggregates validation results and reports `compositionStatus` as either `"pass"` or `"fail"`.

### Programmatic Access to Raw Metrics

Import the `validate` function to inspect metrics directly:

```js
const { validate } = await import('../archify/bin/archify.mjs')
const receipt = await validate('examples/web-app.json', { quality: 'showcase' })
console.log(receipt.validation.composition)

```

The returned object structure:

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

```

### Test Suite Assertions

The validation metrics are used to enforce quality in CI. Example test pattern from [`archify/test/render-output-checks.test.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/test/render-output-checks.test.mjs):

```js
import { strict as assert } from 'assert'
import { validate } from '../../archify/bin/archify.mjs'

const receipt = await validate('examples/web-app.json', { quality: 'showcase' })
assert.equal(receipt.validation.composition.metrics.properCrossings, 0)
assert.equal(receipt.validation.composition.metrics.containerBorderRuns, 0)

```

## Key Implementation Files

| File | Responsibility |
|------|--------------|
| [`archify/bin/archify.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs) | CLI entry point; aggregates `compositionStatus` into validation reports |
| [`scripts/build-gallery.mjs`](https://github.com/tt-a1i/archify/blob/main/scripts/build-gallery.mjs) | Gallery generator; displays the four composition metrics in the receipt UI |
| [`archify/test/render-output-checks.test.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/test/render-output-checks.test.mjs) | Test assertions on composition metrics for fixtures |
| [`archify/test/gallery.test.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/test/gallery.test.mjs) | Zero‑crossing‑debt enforcement for gallery entries |

The validator runs deterministically across all interfaces, ensuring that diagrams accepted into the **showcase** quality profile meet consistent geometric standards.

## Summary

- **Four metrics** define visual quality: `properCrossings`, `containerBorderRuns`, `microSegmentCount`, and `shortInteriorSegmentCount`
- **Deterministic validation** runs on every diagram before acceptance
- **CLI, API, and test suite** all expose identical composition check results
- **Showcase quality profile** requires `compositionStatus: "pass"` with zero or minimal metric values
- **Source files** in `bin/archify.mjs`, `scripts/build-gallery.mjs`, and the test suite implement and enforce these checks

## Frequently Asked Questions

### What happens if a diagram fails composition checks?

The validator returns `compositionStatus: "fail"` and includes the specific metric values in the receipt. The CLI will report the failure, and programmatic consumers can inspect `receipt.validation.composition.metrics` to identify which thresholds were exceeded. Failed diagrams are rejected from the showcase gallery.

### Can composition checks run without the showcase profile?

The composition validator is tied to quality profiles. To enable composition validation, specify `--quality showcase` or pass `quality: 'showcase'` in the options object. Lower profiles may skip geometric validation for faster iteration during development.

### Why are proper crossings counted separately from other edge intersections?

Proper crossings specifically exclude intersections at nodes, which are topological connections rather than geometric accidents. This distinction matters because layout algorithms can sometimes eliminate crossings by adjusting node positions, whereas node‑incident intersections are inherent to the graph structure.

### How do I add composition checks to my own test suite?

Import the `validate` function from `archify/bin/archify.mjs`, call it with `quality: 'showcase'`, and assert on the `receipt.validation.composition.metrics` object. All four metrics are available as numbers; assert specific thresholds or require `status: 'pass'` for blanket validation.