# How Archify's Quality Profiles Differ: Standard vs. Showcase Validation Modes

> Understand the key differences between Archify's standard and showcase quality profiles. Learn how standard offers flexible validation while showcase enforces strict rules for optimal results.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-09-01

---

**The two quality profiles differ primarily in strictness: _standard_ permits loose geometry with warning-only feedback for composition issues, while _showcase_ enforces hard limits on bends, stretch, spacing, and crossings with non-zero exit codes on failure.**

Archify uses **quality profiles** to control how strictly a diagram's visual composition is validated. The `standard` and `showcase` profiles ship as defaults in the tt-a1i/archify repository, letting you toggle between rapid iteration and production-ready polish.

## What Each Quality Profile Does

### Standard Profile: Fast Feedback for Exploration

The **standard** profile prioritizes speed and permissiveness during diagram development.

- **Geometry errors** fail the build
- **Composition issues** generate **warnings** that do not affect exit status
- **Bend budget**: Up to 12 bends per route (very relaxed)
- **Stretch limit**: No hard limit (default allows > 5 stretch)
- **Minimum segment length**: Zero is allowed
- **Node/label spacing**: Advisory only
- **Crossings & bridges**: Crossings reported as warnings; bridges allowed

Use `standard` for rapid iteration, early-stage diagrams, and internal prototypes.

### Showcase Profile: Strict Gates for Production

The **showcase** profile enforces **hard errors** for the same violations that `standard` warns about.

- **Validation outcome**: All issues treated as **errors**; CLI exits with non-zero code
- **Bend budget**: Maximum 2 bends per route
- **Stretch limit**: ≤ 1.35 stretch per segment
- **Minimum segment length**: ≥ 16 px (and ≥ 8 px for terminal segments)
- **Node/label spacing**: Enforced minimum gaps (≈ 40 px node gap, 20 px container gutter, 4 px label clearance)
- **Crossings & bridges**: Any crossing, bridge jump, or "proper X" overlap is an error

Use `showcase` for final README-showcase diagrams, Gallery artifacts, and checked-in proof-of-concepts.

## Activating Each Quality Profile

### Command Line Interface

As implemented in `scripts/package-smoke.mjs`, use the `--quality` flag:

```bash

# Validate a diagram using the permissive standard profile

archify validate workflow my-diagram.json --quality standard

# Validate the same diagram with the strict showcase profile

archify validate workflow my-diagram.json --quality showcase

```

### Architecture JSON Configuration

Set `meta.quality_profile` in your diagram file. The schema definition in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) specifies the enum as `"standard" | "showcase"`:

```json
// In an architecture JSON file – explicit profile selection
{
  "meta": {
    "title": "Customer checkout flow",
    "quality_profile": "showcase"
  },
  "nodes": [...]
}

```

If `meta.quality_profile` is omitted, Archify **defaults to standard**.

### Programmatic API Usage

```javascript
// Programmatic use via the Archify API (Node.js)
import { validate } from '@archify/core';

const receipt = await validate('workflow', diagram, { quality: 'showcase' });

if (!receipt.ok) {
  console.error('Showcase validation failed:', receipt.errors);
}

```

## Where the Profiles Are Defined

| File | Role |
|------|------|
| [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md) | Explains when to use each profile—standard for exploration, showcase for polished artifacts |
| [`docs/research-visual-evolution-round-44.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-44.md) | Detailed table of the two profiles and concrete geometry bounds |
| [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) | Schema definition of the `quality_profile` enum |
| `scripts/package-smoke.mjs` | CLI driver showing `--quality` flag implementation |
| `archify/test/…/*.json` | Test fixtures with `meta.quality_profile` set to either profile for regression testing |

According to [`docs/research-visual-evolution-round-44.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-44.md) (the "Round 44" research note), the policy matrix explicitly maps how `standard` produces advisory warnings while `showcase` rejects identical violations as hard errors.

## Summary

- **Standard profile**: Permissive, warning-based feedback, 12 bends allowed, no stretch limit—ideal for rapid iteration
- **Showcase profile**: Strict error enforcement, 2 bends max, 1.35 stretch limit, enforced spacing—required for production artifacts
- **Default behavior**: Falls back to `standard` unless `--quality showcase` or `meta.quality_profile: "showcase"` is specified
- **Exit codes**: `standard` passes despite composition warnings; `showcase` fails with non-zero status on any violation

## Frequently Asked Questions

### How do I switch from standard to showcase validation in Archify?

Add `--quality showcase` to your CLI command or set `"quality_profile": "showcase"` in the `meta` object of your architecture JSON. The repository defaults to `standard` when neither is specified.

### Why does my diagram pass locally but fail in CI?

Your local environment likely uses the default `standard` profile, which treats composition issues as warnings. CI pipelines should explicitly use `--quality showcase` to catch visual quality regressions before merge.

### What happens if I exceed the 2-bend limit in showcase mode?

The validator returns a hard error, adds the violation to `receipt.errors`, and the CLI exits with a non-zero status code. In `standard` mode, the same geometry would generate only a warning with no exit code impact.