How Archify's Composition Checker Identifies Diagram Layout Issues

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:

archify render diagram.yaml | archify check composition

Programmatic API

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

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:

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.

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