Archify Quality Profiles: Standard vs. Showcase Differences Explained

In Archify, standard (the default) treats composition issues like proper crossings and overlaps as warnings that don't block rendering, while showcase elevates those same checks to hard errors that fail the build and reject the artifact.

The tt-a1i/archify repository implements two quality profiles that control how strictly diagram composition is validated. These profiles determine whether visual imperfections generate mere feedback or halt the pipeline entirely.

How the Profiles Work

Archify evaluates diagrams against two categories of checks:

• Safety errors: Issues that break rendering (edges through nodes, non-finite paths)
• Composition issues: Visual imperfections (proper crossings, unrelated overlaps, container-border runs)

The profile you choose decides which category composition issues fall into.

Standard Profile: Permissive Engineering Mode

The standard profile is optimized for iterative development of real-world diagrams.

Under this mode:

• Safety errors fail and block rendering
• Composition issues become warnings that don't abort the process
• The CLI returns exit code 0 even when warnings exist
• The receipt includes warnings for inspection

This profile allows developers to work with dense, complex diagrams without every visual imperfection blocking their workflow.

The schema defines "standard" as the default value in archify/schemas/architecture.schema.json at line 21:

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

Showcase Profile: Strict Quality Gates

The showcase profile enforces polished visual standards for public-facing artifacts.

Under this mode:

• Safety errors still fail (unchanged from standard)
• Composition checks become hard errors for:
  • Proper interior X crossings
  • Unrelated collinear overlaps
  • Routes running collinearly along container borders
• The CLI returns a non-zero exit code on any error
• The artifact is rejected for showcase generation

This profile ensures README images and gallery examples meet strict visual quality standards.

Behavioral Differences in Code

The test suite in archify/test/render-output-checks.test.mjs (lines 246-250) confirms the divergence. A proper crossing that generates a warning under standard becomes a blocking error under showcase.

Design documentation in docs/research-visual-evolution-round-44.md (lines 48-53) explains this intentional separation: standard prioritizes developer velocity, while showcase prioritizes presentation quality.

Practical Usage Examples

Default Standard Rendering

# Implicit default

archify render architecture diagram.json out.html

# Explicit standard (equivalent)

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

Returns exit code 0 with warnings in the receipt. The HTML artifact is produced regardless of composition issues.

Strict Showcase Rendering

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

Returns non-zero exit code if proper crossings, overlaps, or border runs are detected. The artifact is rejected.

Inspecting Active Profile

archify validate architecture diagram.json --json

Output includes the resolved profile:

{
  "composition": {
    "profile": "standard"
  }
}

When to Use Each Profile

Use Case	Recommended Profile	Rationale
Daily development, CI diagrams	standard	Don't block builds on cosmetic issues
Internal documentation	standard	Velocity over pixel perfection
Public README/Gallery images	showcase	Guarantee polished presentation
Release artifacts	showcase	Prevent substandard visuals from shipping

Summary

• Standard profile (archify/schemas/architecture.schema.json#L21): warnings for composition issues, exit code 0, designed for engineering workflows
• Showcase profile: hard errors for composition issues, non-zero exit code, designed for public artifacts
• Same safety checks apply regardless of profile; only composition severity changes
• Test verification: archify/test/render-output-checks.test.mjs#L246-L250 validates the warning vs. error behavior

Frequently Asked Questions

How do I switch between standard and showcase profiles in Archify?

Pass --quality showcase or --quality standard to any archify render command. If omitted, standard is used. The profile is also configurable in your architecture.json under the composition.profile field.

Does the showcase profile catch more errors than standard?

No. Both profiles run identical validation checks. The difference is severity: standard logs composition issues as warnings while showcase treats them as fatal errors. Safety errors (edges through nodes, non-finite paths) always fail regardless of profile.

Can I use showcase profile in CI but standard locally?

Yes. Set composition.profile: "standard" in your configuration file for local development, then override in CI: archify render ... --quality showcase. This catches visual regressions before they reach public documentation.

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