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

> Validate Archify diagram structure with standard and showcase quality profiles. Ensure robust diagram composition and layout with Archify's two-stage validation process.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md#L88), 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](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md#L1060)
- **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:

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

```

```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`](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs#L78).

## Handling Composition Check Failures

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md) | Documents v2.16.0 introduction of the composition receipt system at line 88 |

The [preview tests](https://github.com/tt-a1i/archify/blob/main/archify/test/preview.test.mjs#L232) 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](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md).

### 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](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md#L88). 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](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md#L1060) defines this rule, and such crossings increment `properCrossings` and fail showcase validation.