Standard vs Showcase Quality Profiles in Archify: Complete Validation Guide

Archify's standard and showcase quality profiles differ in strictness: standard treats composition issues as warnings for engineering workflows, while showcase treats them as hard errors for public-facing artifacts.

This guide explains how Archify's two quality profiles control validation behavior during diagram rendering. The standard profile prioritizes developer velocity by allowing visual imperfections, while the showcase profile enforces strict composition standards for polished outputs.

What Are Archify Quality Profiles?

Archify validates architectural diagrams against two profile levels defined in archify/schemas/architecture.schema.json (line 21):

["standard", "showcase"]

These profiles determine whether composition checks produce warnings or errors, directly affecting CLI exit codes and artifact generation.

Standard Profile: Engineering-First Validation

The standard profile is the default setting for everyday diagram development.

Validation Behavior

• Safety errors (edges through nodes, non-finite paths) → Fail and abort
• Composition issues (proper crossings, unrelated overlaps, container-border runs) → Warnings only

Exit Behavior

The CLI returns exit code 0 even when warnings exist. The receipt contains warnings for inspection without blocking the build process.

# Default standard profile

archify render architecture diagram.json out.html
#same as --quality standard
#exits 0 with warnings in receipt, artifact produced

Use standard for iterating on dense, real-world diagrams where visual perfection is secondary to functional correctness.

Showcase Profile: Publication-Ready Strictness

The showcase profile is an opt-in setting for Gallery and README artifacts shown to end-users.

Validation Behavior

• Safety errors → Same hard failures as standard
• Composition issues → Upgraded to hard errors:
  • Proper interior X crossings
  • Unrelated collinear overlaps
  • Routes running collinearly along container borders

Exit Behavior

The CLI returns a non-zero exit code on any composition error. The receipt reports errors and rejects the artifact for showcase generation.

# Strict showcase validation

archify render architecture diagram.json out.html --quality showcase
#exits non-zero if composition errors found, artifact rejected

Use showcase when visual polish directly impacts user perception of your documentation.

Profile Comparison: Standard vs Showcase

Aspect	Standard	Showcase
Default status	Yes	Opt-in
Target use case	Engineering diagrams	Public-facing artifacts
Proper X crossings	Warning	Error
Unrelated overlaps	Warning	Error
Container-border runs	Warning	Error
CLI exit code	0 (with warnings)	Non-zero (with errors)
Artifact output	Produced	Rejected on error

Implementation and Source References

Schema Definition

The allowed values are declared in archify/schemas/architecture.schema.json at line 21:

"quality_profile": {
  "enum": ["standard", "showcase"]
}

Test Suite Verification

Behavioral differences are confirmed in archify/test/render-output-checks.test.mjs (lines 246-250), where a proper crossing is recorded as a warning under standard but an error under showcase.

Design Documentation

The original design intent is documented in docs/research-visual-evolution-round-44.md (lines 48-53) within the "Composition Receipt" research note, summarizing profile purposes and exit semantics.

Practical Profile Management

Inspect Active Profile

Validate a diagram and see which profile applies:

archify validate architecture diagram.json --json

Output includes: "composition.profile": "standard" or "showcase"

CI/CD Integration

# Development builds: allow warnings

archify render architecture diagram.json out.html

# Release builds: enforce showcase standards

archify render architecture diagram.json out.html --quality showcase || exit 1

Summary

• Standard profile optimizes for developer velocity with warning-only composition checks
• Showcase profile enforces visual perfection through hard composition errors
• Profile selection affects CLI exit codes and artifact acceptance
• Implementation spans schema definition (architecture.schema.json), test suites (render-output-checks.test.mjs), and design docs (research-visual-evolution-round-44.md)
• Choose standard for engineering iteration, showcase for public documentation

Frequently Asked Questions

What is the default quality profile in Archify?

Standard is the default. Running archify render without a --quality flag automatically applies the standard profile, which allows composition warnings without failing the build.

Can I override the quality profile per diagram?

Yes, via CLI flag. Use --quality showcase or --quality standard on any render or validate command. The active profile appears in JSON validation output under composition.profile.

Why does showcase reject artifacts that standard accepts?

Different failure modes. Standard returns exit code 0 with warnings in the receipt, producing the artifact. Showcase returns non-zero exit codes for the same composition issues, rejecting the artifact to prevent publication of visually imperfect diagrams.

Where are the quality profile rules defined?

Three source locations: The quality_profile enum lives in archify/schemas/architecture.schema.json. Behavioral tests are in archify/test/render-output-checks.test.mjs. Design rationale appears in docs/research-visual-evolution-round-44.md.

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