Archify Quality Profile Composition Checks: How to Validate Diagram Structure with Standard and Showcase Modes

Archify validates diagram structural quality through a two-stage process—schema and layout validation followed by a composition receipt that audits four key metrics based on your selected quality profile (--quality standard or --quality showcase).

The tt-a1i/archify CLI tool provides deterministic, machine-readable proof that architecture diagrams meet visual-design standards before they ship to production. The composition audit system, introduced in v2.16.0 according to the CHANGELOG.md, enforces architectural best practices through configurable quality profile composition checks.

How Quality Profile Composition Checks Work

Archify's validation pipeline runs in two distinct phases:

1. Schema and layout validation — structural correctness of nodes, edges, and positioning
2. Composition receipt audit — quality assessment based on your selected profile

The quality profile you choose with the --quality flag determines whether composition issues surface as warnings or hard failures.

Standard vs. Showcase Quality Profiles

Profile	Behavior	Best For
standard	Basic layout checks with composition issues reported as warnings only	Rapid iteration, draft diagrams
showcase	Strict composition contract; hard failures on edge crossings, border runs, short segments	Production-ready artifacts

Standard Profile Composition Checks

The standard profile in Archify quality profile composition checks performs foundational layout validation including orthogonal arrows, route crossing detection, and label clearance analysis. All composition-related findings remain non-blocking—you receive warnings in the output but the CLI exits successfully.

Showcase Profile Composition Checks

The showcase profile enforces a stricter composition contract. Four specific metrics become blocking validation gates:

• properCrossings — Only same-direction or shared-endpoint edge crossings are permitted; any crossing of an unrelated opaque node triggers a hard failure per the authoring contract rules
• containerBorderRuns — Long edges running along structural borders are disallowed
• microSegmentCount — Route segments shorter than 8px are rejected
• shortInteriorSegmentCount — Interior segments must be at least 16px

The Composition Receipt JSON Structure

When running archify validate with the --json flag, the CLI returns a structured receipt. Here's a passing showcase validation:

npx archify validate examples/web-app.architecture.json \
    --quality showcase \
    --json

{
  "validation": {
    "checksPassed": 9,
    "checkCount": 9,
    "compositionProfile": "showcase",
    "compositionStatus": "pass"
  },
  "composition": {
    "properCrossings": 0,
    "containerBorderRuns": 0,
    "microSegmentCount": 0,
    "shortInteriorSegmentCount": 0
  }
}

The compositionStatus field is the critical gate: "pass" allows artifact delivery, while "fail" causes the CLI to exit with an error as implemented in archify/bin/archify.mjs.

Handling Composition Check Failures

When Archify quality profile composition checks detect violations in showcase mode, the CLI aborts with descriptive error messaging:

npx archify validate bad-diagram.json --quality showcase --json

Error: compositionStatus "fail": 1 improper crossing (composition/proper-crossing)

This strict failure mode ensures that only diagrams meeting all compositional standards proceed to production environments.

Source Files Defining Composition Behavior

These key files in the tt-a1i/archify repository implement and document the quality profile composition checks:

File	Purpose
archify/references/authoring-contract.md	Defines composition rules including proper crossing classification, container-border run detection, and segment length requirements
archify/bin/archify.mjs	CLI entry point that prints receipts and handles exit codes for composition failures at line 78
archify/test/preview.test.mjs	Test suite asserting that valid showcase diagrams yield compositionStatus: 'pass' at line 232
CHANGELOG.md	Documents v2.16.0 introduction of the composition receipt system at line 88

The preview tests specifically validate that the showcase quality profile produces deterministic pass/fail results, ensuring regression safety for the composition audit logic.

Choosing Between Quality Profiles

Select your Archify quality profile composition checks strategy based on workflow stage:

• Development phase — Use --quality standard for fast feedback without blocking progress on aesthetic refinements
• CI/CD gates — Use --quality showcase to enforce compositional standards before artifact promotion
• Final delivery — Require showcase pass status as a deployment prerequisite

The deterministic JSON output from both profiles enables automated tooling: parse compositionStatus in scripts, generate compliance reports, or trigger downstream workflows only on passing validations.

Summary

• Archify validates diagrams through schema checks plus a composition receipt governed by quality profile selection
• Standard profile reports composition issues as warnings; showcase profile enforces hard failures
• Four metrics—properCrossings, containerBorderRuns, microSegmentCount, shortInteriorSegmentCount—determine pass/fail status
• The CLI returns machine-readable JSON receipts via --json and exits with error on showcase failures per archify.mjs
• Reference the authoring contract for precise rule definitions and the test suite for expected behavior validation

Frequently Asked Questions

What is the minimum segment length requirement in Archify showcase mode?

The showcase profile requires every non-zero route segment to be at least 8 pixels (microSegmentCount threshold) and all interior segments to be at least 16 pixels (shortInteriorSegmentCount threshold). These rules are codified in the authoring contract.

How do I programmatically check if a diagram passes composition checks?

Parse the JSON output from archify validate --quality showcase --json and inspect the validation.compositionStatus field. A value of "pass" indicates compliance; "fail" triggers a CLI error exit that you can catch in shell scripts or CI pipelines.

When were composition receipts introduced to Archify?

The composition receipt system was added in Archify v2.16.0, as documented in CHANGELOG.md line 88. This release established the standard and showcase quality profile framework for automated diagram validation.

What causes an improper crossing failure in showcase mode?

An improper crossing occurs when an edge crosses an unrelated opaque node—any crossing where the nodes do not share directionality or a common endpoint. The authoring contract at line 1060 defines this rule, and such crossings increment properCrossings and fail showcase validation.

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