# How Archify's Composition Checker Identifies Diagram Layout Issues

> Learn how Archify's composition checker finds diagram layout issues. It parses SVG data and uses geometric rules to detect edge crossings, ambiguous corridors, and label clearance violations.

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

---

**Archify's composition checker validates diagram quality by parsing SVG routing data and running geometric rule functions that detect visual problems like edge crossings, ambiguous corridors, and label clearance violations.**

The **Archify composition checker** is an automated validation engine built into the `tt-a1i/archify` repository that analyzes generated architectural diagrams for layout flaws. It processes the SVG output of diagram renders to ensure visual clarity and professional presentation. The system extracts geometric data from edge paths, applies rule-based heuristics, and produces structured reports that flag issues ranging from minor alignment problems to critical intersection errors.

## Three-Stage Validation Pipeline

The composition checker operates through a structured pipeline that transforms raw SVG output into actionable quality metrics.

### Stage 1: Extracting Routing Data from SVG

When Archify renders a diagram, it emits SVG elements where each edge contains a `data-composition-points` attribute (e.g., `data-composition-points="20,60;200,60"`). The checker, implemented in `archify/bin/visual-check.mjs`, walks the SVG DOM and reads these composition points to build an internal model of nodes, relationships, and routing segments. This extraction phase converts raw vector graphics into a traversable geometric structure that subsequent rules can analyze.

### Stage 2: Rule-Based Layout Analysis

The extracted model feeds into a collection of specialized rule functions that scan for specific geometric violations. Each rule targets a distinct visual artifact:

- **Proper-Crossing**: Detects X-shaped intersections where two edges cross without a proper node at the junction.
- **Ambiguous-Corridor**: Identifies overlapping parallel corridors that create visual confusion about relationship paths.
- **Label-Route-Clearance**: Verifies that edge labels maintain adequate distance from their associated paths using profile-specific thresholds.
- **Container-Border-Run**: Ensures relationship edges do not intersect container borders inappropriately.
- **Micro-Segment-Count / Short-Segment-Count**: Tallies tiny path fragments that contribute to visual clutter and rendering artifacts.

Every rule returns a numeric metric (e.g., `properCrossings`, `ambiguousCorridors`) and generates issue objects with unique codes like `composition/proper-crossing` and severity levels (`warning` or `error`).

### Stage 3: Aggregating the Composition Report

After rule execution, the checker assembles a structured `composition` object defined in the test fixtures at `archify/test/render-output-checks.test.mjs`. The report includes the validation profile, overall pass/fail status, aggregated metrics, error and warning counts, detailed issue listings with coordinates, and suggested limits for bends, stretch, and segment lengths.

## Working with the Composition Checker

Developers can invoke validation through command-line interfaces or programmatic APIs.

### CLI Usage

Run composition validation directly from the command line by piping rendered output through the check command:

```bash
archify render diagram.yaml | archify check composition

```

### Programmatic API

Integrate validation into Node.js applications using the Archify SDK:

```javascript
import { renderDiagram, validateComposition } from '@tt-a1i/archify';

// Render diagram to SVG string
const svg = await renderDiagram('my-diagram.yaml');

// Execute composition analysis
const { composition } = await validateComposition(svg);

// Handle results
if (composition.status === 'fail') {
  console.log('Layout issues detected:');
  composition.issues.forEach(i => 
    console.log(`[${i.severity}] ${i.code}`)
  );
}

```

### Test Assertions

Validate composition behavior in your own test suites using patterns from `archify/test/render-output-checks.test.mjs`:

```javascript
test('proper crossing detection', async () => {
  const result = await renderAndValidate('layout-proper-crossing.yaml');
  assert.equal(result.composition.profile, 'standard');
  assert.deepEqual(result.composition.summary, { errors: 0, warnings: 1 });
  assert.equal(result.composition.metrics.properCrossings, 1);
  assert.equal(result.composition.issues[0].code, 'composition/proper-crossing');
});

```

## Summary

- The **Archify composition checker** validates SVG diagram output through a three-stage pipeline: data extraction, rule analysis, and report generation.
- Core rules detect **proper crossings**, **ambiguous corridors**, **label clearance violations**, **container border runs**, and **micro-segments**.
- The system outputs structured reports with metrics, issue codes, and severity levels via `archify/bin/visual-check.mjs`.
- Developers can invoke validation via CLI pipes or the `validateComposition` JavaScript API.
- Test fixtures in `archify/test/render-output-checks.test.mjs` demonstrate how to assert specific layout violations programmatically.

## Frequently Asked Questions

### Where is the composition checker implementation located?

The core implementation resides in `archify/bin/visual-check.mjs`, which parses SVG documents, executes layout rule functions, and generates the composition report structure consumed by the Archify UI.

### How does the checker detect X-shaped intersections without nodes?

The **Proper-Crossing** rule scans the routing model for edge segments that intersect without a shared node point, incrementing the `properCrossings` metric and flagging a `composition/proper-crossing` issue when such geometric violations occur.

### What threshold profiles does the composition checker support?

The checker supports profile-specific thresholds (such as `standard`) that define limits for `bendsPerRelationship`, `stretch` ratios, `segmentPx` minimums, and `microSegmentPx` values, all returned in the `suggestedLimits` object of the report.

### Can composition validation be integrated into CI/CD pipelines?

Yes. Use the CLI command `archify check composition` piped from render output, or programmatically assert on `composition.status` being `'pass'` in automated tests to enforce visual quality gates before deployment.