Standard vs Showcase Quality Profiles in Archify: Key Differences Explained

Archify's standard quality profile treats composition issues as warnings with exit code 0, while showcase promotes the same checks to hard errors with non-zero exit codes to block polished artifacts.

When rendering architecture diagrams in Archify, you choose between two quality profiles that determine how strictly the tool validates visual composition. These profiles exist in archify/schemas/architecture.schema.json as an enum with values ["standard","showcase"]【line 21】. Understanding their differences helps you iterate faster during development while maintaining high standards for public-facing documentation.

How the Standard Profile Works

The standard profile is Archify's default mode for everyday engineering workflows.

• Safety errors (edges through nodes, non-finite paths) fail immediately
• Composition issues (proper crossings, overlaps, container-border runs) become warnings only
• CLI returns exit code 0 even when warnings exist
• The receipt contains warnings for inspection without blocking the artifact

This permissive approach lets developers work with dense, real-world diagrams without interruption.

How the Showcase Profile Works

The showcase profile is an opt-in stricter mode for polished Gallery and README artifacts.

• Safety errors still fail as in standard
• Composition checks become hard errors for:
  • Proper interior X crossings
  • Unrelated collinear overlaps
  • Routes running collinearly along container borders
• CLI returns non-zero exit code when any composition error exists
• The artifact is rejected for showcase generation

According to the design document in docs/research-visual-evolution-round-44.md【profile table, lines 48-53】, this profile enforces "a stricter visual standard for the public-facing examples."

Practical Usage Examples

Select your profile via the --quality flag:

# Default standard profile — warnings don't block output

archify render architecture diagram.json out.html

# → exits 0, receipt contains any composition warnings

# Explicit showcase profile — composition errors block output

archify render architecture diagram.json out.html --quality showcase

# → exits non-zero if proper X crossing or similar error found

Inspect the active profile programmatically:

archify validate architecture diagram.json --json

The JSON output includes "composition.profile": "standard" or "showcase" depending on what was resolved.

Behavioral Differences in Test Suite

The test file archify/test/render-output-checks.test.mjs【lines 246-250】demonstrates the core behavioral difference: a proper crossing is recorded as a warning under standard but as an error under showcase. This test validates that the profile selection directly affects receipt severity levels and exit semantics.

When to Use Each Profile

Scenario	Recommended Profile
Daily development and iteration	standard
CI/CD with existing diagrams	standard
Public documentation and READMEs	showcase
Gallery publications and demos	showcase
Backwards-compatible rendering	standard

Summary

• Standard profile: Default, warning-centric, exit 0 on composition issues, ideal for engineering workflows
• Showcase profile: Opt-in, error-centric, non-zero exit on composition issues, blocks polished artifact generation
• Configuration: Set via --quality flag or implied by default; enum declared in architecture.schema.json
• Validation: Test suite confirms warning vs. error behavior per profile

Frequently Asked Questions

How do I enable the showcase quality profile in Archify?

Pass --quality showcase to any archify render architecture command. Without this flag, the tool defaults to standard.

Does the showcase profile ignore safety errors?

No. Both profiles treat safety errors (edges through nodes, non-finite paths) as hard failures. The difference lies strictly in composition validation severity.

Where is the quality profile defined in the codebase?

The allowed values are declared in archify/schemas/architecture.schema.json【line 21】. Design rationale appears in docs/research-visual-evolution-round-44.md, with behavioral tests in archify/test/render-output-checks.test.mjs.

Can I migrate a standard diagram to showcase without re-rendering?

Run archify validate architecture diagram.json --quality showcase --json first. This checks whether your existing diagram would pass showcase criteria before you attempt a render that might fail with a non-zero exit code.

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