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

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:

# 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 specifies the enum as "standard" | "showcase":

// 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

// 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	Explains when to use each profile—standard for exploration, showcase for polished artifacts
docs/research-visual-evolution-round-44.md	Detailed table of the two profiles and concrete geometry bounds
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 (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.

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