What Are the Artifact Composition Checks in Archify? A Complete Technical Guide

Archify validates the structural integrity of every generated artifact by executing five specific composition checks that verify element relationships, prevent visual ambiguity, and ensure SVG readability.

The tt-a1i/archify repository implements a rigorous validation pipeline for diagram generation. These artifact composition checks run automatically after rendering to guarantee that relationships, containers, and labels maintain clear visual separation and semantic correctness.

The Five Core Artifact Composition Checks

Archify defines its validation suite in archify/bin/archify.mjs as a Set named COMPOSITION_CHECKS (lines 174‑181). Each check targets a specific structural aspect of diagram composition:

• label_route_clearance: Verifies that relationship labels maintain sufficient distance from their associated routes, preventing text overlap that reduces legibility.

• relationship_crossings: Detects unintended line intersections between relationships that could create visual confusion or ambiguity.

• relationship_corridors: Ensures that distinct relationship paths remain visually separate and do not merge into indistinguishable bundles.

• container_border_runs: Validates that routes crossing container borders pass perpendicularly through clear openings, preserving the container's visual framing integrity.

• route_rhythm: Measures the smoothness of relationship paths, flagging routes that are overly jagged or cramped.

These checks are executed by the helper script archify/scripts/check-render-output.mjs, which processes the rendered SVG and reports any validation failures.

How to Run Artifact Composition Checks

Using the CLI Check Command

You can explicitly validate a rendered artifact using the check subcommand. This invokes the composition validators and prints specific failure details:

# Render a workflow diagram first

archify render workflow examples/agent-tool-call.workflow.json out.html

# Run composition checks on the output

archify check out.html

Validation During Delivery

When delivering artifacts, Archify automatically runs composition checks and includes the results in the delivery receipt. Use the --json flag to receive structured output:

archify deliver workflow examples/agent-tool-call.workflow.json --json

The JSON receipt contains the composition profile and status:

{
  "validation": {
    "compositionProfile": "showcase",
    "compositionStatus": "pass"
  }
}

If validation fails, compositionStatus shows "fail" and the receipt lists specific check violations. Archify also provides suggested fixes via the COMPOSITION_FIXES mapping defined in archify/bin/archify.mjs.

Programmatic Access to Composition Checks

For custom integrations, you can import the validator set directly from the CLI module. The COMPOSITION_CHECKS Set contains the check identifiers used by the validation engine:

import { COMPOSITION_CHECKS } from '../archify/bin/archify.mjs';

function runChecks(diagramSvg) {
  const results = [];
  for (const check of COMPOSITION_CHECKS) {
    const passed = performCheck(check, diagramSvg); // Internal implementation
    results.push({ check, passed });
  }
  return results;
}

The actual check logic resides in archify/scripts/check-render-output.mjs, which the CLI invokes after rendering completes.

Summary

• Archify performs five specific artifact composition checks defined in archify/bin/archify.mjs to validate diagram structural integrity.
• The COMPOSITION_CHECKS Set contains identifiers for label clearance, relationship crossings, corridor separation, container border validation, and route smoothness.
• Validation runs automatically during delivery or explicitly via the archify check command using check-render-output.mjs.
• Results appear in JSON delivery receipts with compositionStatus fields indicating "pass" or "fail".
• Failed checks trigger suggestions from the COMPOSITION_FIXES mapping to help authors correct visual issues.

Frequently Asked Questions

What happens if an artifact composition check fails?

When a check fails, Archify sets compositionStatus to "fail" in the delivery receipt and lists the specific checks that did not pass. The tool also references COMPOSITION_FIXES to provide actionable suggestions for correcting the diagram layout, such as adjusting route paths or increasing label offsets.

Where are the artifact composition checks defined in the source code?

The check identifiers are defined as a Set named COMPOSITION_CHECKS at lines 174‑181 in archify/bin/archify.mjs. The actual validation logic and execution engine reside in archify/scripts/check-render-output.mjs, which iterates through the set and applies each check to the rendered SVG output.

Can I run specific composition checks selectively?

The checks are defined as a cohesive Set in COMPOSITION_CHECKS within archify/bin/archify.mjs. While the standard CLI commands execute all checks during delivery, the modular architecture allows programmatic consumers to iterate selectively over specific checks when using the internal JavaScript API, though the tool defaults to running the complete validation suite.

How does Archify measure route rhythm in diagrams?

The route_rhythm check analyzes the smoothness and spacing of relationship paths within the SVG. It flags routes that contain excessive jagged angles or cramped segments that could impair readability, ensuring that connections between elements follow visually clean trajectories with consistent spacing.

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