Archify Quality Profiles: Standard vs Showcase Explained

Archify provides two quality profiles—standard (default) and showcase—that control how strictly composition checks are applied to diagrams, with standard treating composition issues as warnings and showcase treating them as hard errors.

Archify is an open-source diagram rendering tool from tt-a1i/archify that validates architectural diagrams for both safety and visual composition. The quality profile system lets developers choose between rapid iteration and publication-ready polish. Understanding these profiles helps you decide when to permit visual imperfections versus when to enforce strict standards.

---

What Are Quality Profiles in Archify?

Quality profiles determine how the renderer interprets composition issues—visual imperfections like edge crossings through nodes, collinear overlaps, or routes running along container borders. While safety errors (edges through nodes, non-finite paths) always fail regardless of profile, the handling of composition checks differs significantly.

The two profiles are defined in archify/schemas/architecture.schema.json at line 21, which declares the allowed enum values: ["standard","showcase"].

---

The Standard Profile: Engineering-Focused Permissiveness

The standard profile is the default mode optimized for day-to-day development workflows.

What It Validates

• Safety errors (edges through nodes, non-finite paths): hard fail
• Composition issues (proper crossings, unrelated overlaps, container-border runs): warning only

Exit Behavior

The CLI returns exit code 0 even when warnings are present. The composition receipt contains the warnings for inspection, but artifact generation proceeds.

When to Use Standard

Use standard for:

• Dense, real-world engineering diagrams
• Backwards-compatible rendering pipelines
• Rapid iteration where visual perfection is not required

# Render using default standard profile

archify render architecture diagram.json out.html

# Explicitly specify standard (equivalent to above)

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

---

The Showcase Profile: Publication-Ready Strictness

The showcase profile is an opt-in mode for polished, public-facing artifacts like gallery examples and README screenshots.

What It Validates

• Safety errors: still hard fail (unchanged from standard)
• Composition issues: now hard errors for:
  • Proper interior X crossings
  • Unrelated collinear overlaps
  • Routes running collinearly along container borders

Exit Behavior

The CLI returns a non-zero exit code when any composition error is found. The receipt reports the errors, and the artifact is rejected for showcase generation.

When to Use Showcase

Use showcase for:

• Public gallery artifacts
• README and documentation screenshots
• Any output shown to end-users where visual quality reflects project standards

# Render with showcase profile—fails fast on composition errors

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

---

Profile Comparison at a Glance

Aspect	Standard	Showcase
Default?	Yes	No (opt-in)
Safety errors	Hard fail	Hard fail
Proper X crossings	Warning	Error
Unrelated overlaps	Warning	Error
Container-border runs	Warning	Error
CLI exit code	0 (with warnings)	Non-zero
Artifact output	Generated	Rejected on error

The behavioral difference is verified in archify/test/render-output-checks.test.mjs at lines 246-250, where test suites confirm that a proper crossing is recorded as a warning under standard but as an error under showcase.

---

Validating and Inspecting Active Profiles

To check which profile is active for a given validation run:

# Validate and see profile in JSON output

archify validate architecture diagram.json --json

The output includes "composition.profile": "standard" or "composition.profile": "showcase".

The design rationale for these profiles is documented in docs/research-visual-evolution-round-44.md (lines 48-53), which explains the "Composition Receipt" concept and the intentional trade-off between engineering velocity and visual polish.

---

Summary

• Standard profile: Permissive, warning-centric mode for everyday engineering diagrams where rapid iteration matters more than visual perfection.
• Showcase profile: Strict, error-driven mode for public-facing artifacts where composition quality directly impacts project perception.
• Safety errors (edges through nodes, non-finite paths) are non-negotiable and fail in both profiles.
• Composition issues escalate from warnings to errors based on profile selection.

---

Frequently Asked Questions

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

Pass --quality showcase or --quality standard to any archify render or archify validate command. If omitted, standard is the default. The valid values are enforced by the JSON schema in archify/schemas/architecture.schema.json.

Will my CI/CD pipeline fail if I use the standard profile?

Not due to composition warnings. The standard profile returns exit code 0 even when warnings are present, so only safety errors will fail your build. Use showcase if you want composition issues to fail CI checks.

What specific composition issues become errors in showcase mode?

According to the Archify source code and research documentation, showcase promotes three composition checks to hard errors: proper interior X crossings between edges, unrelated collinear overlaps, and any route that runs collinearly along a container border.

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