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

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.

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.

# 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 aggregates validation results and reports compositionStatus as either "pass" or "fail".

Programmatic Access to Raw Metrics

Import the validate function to inspect metrics directly:

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:

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

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	CLI entry point; aggregates compositionStatus into validation reports
scripts/build-gallery.mjs	Gallery generator; displays the four composition metrics in the receipt UI
archify/test/render-output-checks.test.mjs	Test assertions on composition metrics for fixtures
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.

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