What Archify Composition Checks Are Enforced (Standard vs. Showcase Profiles)

Archify enforces two core composition checks—proper-crossing and label-route-clearance—with different severity levels depending on whether you use the standard or showcase quality profile.

Archify is an open-source diagramming tool from tt-a1i/archify that validates rendered architecture diagrams for visual clarity and professional polish. The composition checks module examines the generated SVG output to catch structural issues that could confuse readers or violate diagramming conventions.

Core Composition Checks in Archify

The validation system runs automatically during diagram rendering. Each check targets a specific class of visual problem that commonly occurs in architecture diagrams with many intersecting relationships.

Proper-Crossing Detection

The proper-crossing check identifies ambiguous edge intersections. Specifically, it detects a single "X" formed by two orthogonal edges that cross without sharing an endpoint.

This pattern creates visual ambiguity: readers cannot determine whether the edges connect at that point or simply pass over each other. In proper diagram notation, intersecting relationships should either share a node or use a jump/hop indicator.

// Source: render-output-checks.test.mjs, lines 94-99
// Proper crossing test validation logic
test('flags orthogonal edges crossing without shared endpoint', () => {
  const svg = renderDiagram(intersectingHorizontalAndVertical);
  const result = checkProperCrossing(svg);
  expect(result.severity).toBe(profile === 'showcase' ? 'error' : 'warning');
});

Profile behavior:

• Standard profile: Emits a warning, allowing generation to continue
• Showcase profile: Treats as a hard error, blocking output until resolved

Label-Route-Clearance Validation

The label-route-clearance check ensures relationship labels remain readable. It validates that a relationship label—a <g> element containing a background rectangle—does not overlap any other edge sharing the same source node.

Overlapping labels create clutter and make it difficult to trace which text belongs to which relationship, particularly in dense diagrams with multiple outgoing connections from a single component.

Profile behavior:

• Standard profile: Warning if clearance violation detected
• Showcase profile: Error if any label-edge overlap exists

How Quality Profiles Control Severity

Archify's two-tier quality profile system lets teams choose their strictness level:

Profile	Use case	Proper-crossing	Label-route-clearance
standard	Draft diagrams, internal docs	Warning	Warning
showcase	Client presentations, published artifacts	Error	Error

The profile setting propagates through the check pipeline in render-output-checks.test.mjs, where each test case asserts the expected severity based on the active configuration.

Running Composition Checks in Your Build

Composition checks execute automatically during the render phase. To explicitly validate an existing SVG:

# Validate against standard profile (default)

npx archify validate diagram.svg

# Enforce showcase-quality strictness

npx archify validate diagram.svg --profile=showcase

For programmatic access, the check functions are exported from the core validation module:

import { checkProperCrossing, checkLabelRouteClearance } from 'archify/validate';

const svgElement = await loadSvg('architecture.svg');
const crossingResult = checkProperCrossing(svgElement, { profile: 'showcase' });
const clearanceResult = checkLabelRouteClearance(svgElement, { profile: 'showcase' });

Resolving Common Composition Issues

When checks fail, Archify reports the specific SVG element IDs involved. Typical fixes include:

• Proper-crossing errors: Add a hop/jump marker to one edge, or reposition nodes to eliminate the intersection
• Label-route-clearance errors: Increase labelOffset in relationship styling, or rearrange outgoing edges to diverge at wider angles

Summary

• Archify runs two core composition checks: proper-crossing and label-route-clearance
• Checks operate on the rendered SVG output, not the source diagram model
• Quality profiles determine severity: standard (warnings) versus showcase (hard errors)
• Source implementation lives in render-output-checks.test.mjs with profile-aware test assertions
• Programmatic and CLI interfaces both support explicit profile selection

Frequently Asked Questions

What happens if a composition check fails in showcase mode?

The render operation aborts with a non-zero exit status and a detailed error message identifying the violating elements. You must adjust the diagram layout or styling to resolve the issue before output generation succeeds.

Can I disable specific composition checks?

No. The Archify validation pipeline runs both checks unconditionally. Profile selection only affects whether violations surface as warnings or errors. To override this behavior, you must post-process the SVG outside Archify's native toolchain.

Where are the composition check thresholds configured?

Profile behavior is hardcoded in the test assertions within render-output-checks.test.mjs. There are no user-configurable thresholds for crossing detection sensitivity or minimum label clearance distance in the current release.

Do composition checks affect rendering performance?

Validation adds negligible overhead for typical diagrams. The SVG traversal in checkProperCrossing and checkLabelRouteClearance operates on the already-rendered DOM, with complexity linear to edge and label counts.

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