# What Are the Specific Composition Checks Performed by Archify?

> Discover Archify's seven composition checks: Proper Crossing, Ambiguous Corridor, Container-Border Run, Label-Route Clearance, Desktop Readability, Micro Segment, and Short Interior Segment for diagram validation.

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

---

**Archify validates diagram composition through seven specific geometric and layout checks: Proper Crossing, Ambiguous Corridor, Container-Border Run, Label-Route Clearance, Desktop Readability, Micro Segment, and Short Interior Segment.**

The `tt-a1i/archify` rendering engine analyzes spatial relationships between edges, labels, frames, and nodes to ensure architectural diagrams remain visually clear and semantically unambiguous. These **composition checks performed by Archify** automatically detect layout violations ranging from ambiguous corridor overlaps to micro-segments shorter than 8 pixels, generating actionable diagnostics for each issue detected.

## Core Composition Checks

### Proper Crossing Detection

**Code:** `composition/proper-crossing`

This check detects when two relationship routes intersect in a way that could be confusing or ambiguous to readers. When edges cross without clear differentiation, it becomes difficult to trace data flow between components.

According to the source code in `archify/bin/archify.mjs` (lines 189-195), the fix suggestion for this violation is to **adjust route, via, or channel coordinates** so unrelated relationships use separate corridors.

### Ambiguous Corridor Identification

**Code:** `composition/ambiguous-corridor`

The Ambiguous Corridor check finds overlapping corridor segments where distinct relationships share the same visual corridor, making it hard to differentiate them. This spatial collision occurs when multiple edges occupy identical coordinate ranges.

As implemented in `archify/scripts/check-render-output.mjs` (lines 157-210), the diagnostic recommends adjusting route, via, or channel coordinates so unrelated relationships do not visually merge.

### Container-Border Run Validation

**Code:** `composition/container-border-run`

This check flags when a relationship edge runs along the border of a container frame instead of crossing perpendicularly, which can obscure hierarchy and containment relationships. The violation occurs when routes parallel frame boundaries rather than crossing through designated openings.

The fix, defined in the check configuration, requires routing across the frame perpendicularly through a clear opening.

### Label-Route Clearance Verification

**Code:** `composition/label-route-clearance`

Archify checks that a label's bounding box maintains minimum clearance from the route it annotates, preventing label occlusion that would render text unreadable. This validation ensures typography remains legible against underlying geometry.

Fix suggestions include adjusting `labelAt`, `labelDx`, `labelDy`, `labelSegment`, message-y, or the other relationship route to create adequate spatial separation.

### Desktop Readability Assessment

**Code:** `composition/desktop-readability`

This check ensures that node titles remain legible on a typical desktop viewport (minimum 1440 px width) by avoiding cramped or overly long labels. It validates that diagram dimensions accommodate standard monitor resolutions without requiring excessive zoom.

Remediation options include reducing viewBox width, shortening node copy, widening affected nodes, or splitting the diagram so node context stays at least 6 px.

### Micro Segment Detection

**Code:** `composition/micro-segment`

The Micro Segment check detects segments shorter than the minimum visual length (default **8 px**), which can be invisible or hard to trace in the rendered output. These tiny geometric fragments often result from imprecise coordinate calculations.

The diagnostic, generated in `archify/scripts/check-render-output.mjs`, advises moving the route/channel/via point so every visible segment is at least 8 px.

### Short Interior Segment Analysis

**Code:** `composition/short-interior-segment`

This validation flags interior turns (bends) that are too short (default **< 16 px**), leading to cramped geometry that appears abrupt or cluttered. Unlike micro-segments, this specifically targets corner radii and elbow joints.

The fix requires moving the route/channel/via point so every interior turn has at least 16 px of length.

## Implementation in the Archify Source Code

The composition validation pipeline relies on several key files within the `tt-a1i/archify` repository:

- **`archify/bin/archify.mjs`** (lines 189-195) — Defines the mapping of check codes to suggested fixes, providing the user-facing remediation text for each diagnostic type.

- **`archify/scripts/check-render-output.mjs`** (lines 157-210) — Implements the diagnostic generation logic that constructs human-readable problem descriptions and categorizes issues by severity.

- **`archify/renderers/shared/geometry.mjs`** (lines 455-655) — Contains low-level geometric calculations used by composition checks to measure distances, detect intersections, and calculate bounding boxes.

- **`archify/renderers/architecture/render-architecture.mjs`** (line 311) — Orchestrates the rendering process and ultimately triggers composition validation against the generated SVG output.

- **`archify/test/render-output-checks.test.mjs`** — Provides test coverage verifying that each composition check behaves as expected across various diagram configurations.

## Running Composition Checks Programmatically

You can invoke these composition checks programmatically when processing diagrams through the Archify API:

```javascript
// Example: Running composition checks on a diagram
import { renderDiagram } from 'archify/renderers/architecture/render-architecture.mjs';
import { checkComposition } from 'archify/scripts/check-render-output.mjs';

const diagram = await loadDiagram('my-diagram.json');
const result = renderDiagram(diagram);
const compositionReport = checkComposition(result.composition);

// Print any composition warnings or errors
compositionReport.issues.forEach(issue => {
  console.log(`[${issue.code}] ${issue.message}`);
});

```

When the diagram contains a micro-segment, the output might include:

```

[composition/micro-segment] showcase diagram contains a segment shorter than 8 px – move the route/channel/via point.

```

## Summary

- **Proper Crossing** prevents ambiguous intersections between unrelated relationship routes.
- **Ambiguous Corridor** eliminates overlapping corridor segments that confuse distinct connections.
- **Container-Border Run** enforces perpendicular crossings at frame boundaries to maintain hierarchy clarity.
- **Label-Route Clearance** ensures text remains readable by enforcing minimum distance between labels and edges.
- **Desktop Readability** validates diagram dimensions against 1440 px viewport standards.
- **Micro Segment** rejects geometric fragments shorter than 8 px that may disappear on rendering.
- **Short Interior Segment** requires 16 px minimum lengths for corner bends to prevent visual clutter.

## Frequently Asked Questions

### How does Archify determine which composition checks to run?

The renderer automatically invokes all seven composition checks during the validation pipeline defined in `archify/scripts/check-render-output.mjs`, inspecting the rendered SVG output against geometric thresholds defined in the source code. Each check evaluates specific spatial relationships without requiring explicit user configuration.

### Can I customize the threshold values for micro-segment detection?

According to the source analysis, the default 8-pixel minimum for micro-segments and 16-pixel minimum for short interior segments are hardcoded in the geometry validation logic within `archify/renderers/shared/geometry.mjs` (lines 455-655). Modifying these thresholds requires editing the source constants in that file.

### What file should I examine to add custom composition checks?

New checks should be implemented in `archify/scripts/check-render-output.mjs` following the existing pattern of diagnostic construction (lines 157-210), with corresponding fix suggestions added to `archify/bin/archify.mjs` (lines 189-195). The geometric evaluation logic should be added to `archify/renderers/shared/geometry.mjs`.

### How are composition check results exposed in the API?

The `checkComposition()` function returns a report object containing an `issues` array where each entry includes the check code (`composition/proper-crossing`, etc.), human-readable message, and fix suggestions. This structure allows programmatic access to all diagnostics generated during the rendering pipeline.