Archify Quality Profiles Standard vs Showcase: Key Differences Explained

The Archify standard quality profile provides permissive, advisory validation that renders diagrams with warnings, while the showcase profile enforces strict production-grade visual quality rules that halt rendering on any violation.

Archify, the open-source diagram rendering tool from tt-a1i/archify, uses quality profiles to control how rigorously a diagram's visual composition is validated. Understanding the difference between standard and showcase helps you choose the right trade-off between flexibility and visual fidelity.

What Quality Profiles Control

Quality profiles govern Archify's composition-quality contract—a set of rules covering line crossings, edge bends, node spacing, and container gutters. These rules originate from Archify's Fireworks layout engine and determine whether your diagram renders successfully or fails with validation errors.

Standard Profile: Permissive by Design

The standard profile targets everyday documentation and rapid iteration.

• Default behavior: Archify uses standard automatically when meta.quality_profile is omitted
• Advisory validation: Quality violations trigger warnings but do not block rendering
• CLI usage: archify render diagram.json --quality standard or simply omit the flag

In archify/schemas/common.schema.json, the qualityProfile enum defines standard as a valid value alongside showcase. Examples in the repository demonstrate this profile in practice: the archify-repo.html example embeds data-quality-profile="standard" on its rendered diagram element.

Use standard for internal documentation, drafts, or any scenario where "good enough" readability suffices.

Showcase Profile: Strict Production Quality

The showcase profile guarantees presentation-ready visual output through hard enforcement.

• Strict validation: All composition-quality rules become hard errors—any violation aborts rendering
• Explicit activation: Set meta.quality_profile: "showcase" in your JSON or pass --quality showcase on the CLI
• Quality contract: Enforces zero line crossings, maximum two bends per edge, adequate node spacing, and proper container gutters

According to docs/research-visual-evolution-round-44.md, the showcase profile was introduced as a "named quality profile" that budgets visual quality for showcase renderings. The web-app.html example demonstrates this with data-quality-profile="showcase".

Use showcase for public-facing diagrams, marketing materials, or any context where visual fidelity must be guaranteed.

How to Configure Each Profile

Via CLI Flag

# Standard (default, permissive)

archify render examples/web-app.architecture.json

# Showcase (strict, production-grade)

archify render examples/web-app.architecture.json --quality showcase

The --quality flag is processed in scripts/package-smoke.mjs, which handles CLI argument parsing for Archify's renderer.

Via Meta Field in Source JSON

{
  "meta": {
    "title": "Customer Journey",
    "quality_profile": "showcase"
  },
  "participants": [
    {"id": "user", "type": "person"},
    {"id": "api", "type": "system"}
  ],
  "messages": [
    {"from": "user", "to": "api", "action": "requests data"}
  ]
}

The quality_profile field accepts either "standard" or "showcase" as defined in the JSON schema.

Key Implementation Files

File	Role
archify/schemas/common.schema.json	Defines qualityProfile enum with standard and showcase values
docs/research-visual-evolution-round-44.md	Documents the motivation and behavior of the showcase profile
examples/web-app.html	Live example using data-quality-profile="showcase"
examples/archify-repo.html	Live example using data-quality-profile="standard"
scripts/package-smoke.mjs	Implements CLI --quality flag handling

Comparison at a Glance

Aspect	standard	showcase
Default	Yes (implicit)	No (must specify)
Validation severity	Warnings	Hard errors
Render on violation	Continues	Aborts
Line crossings allowed	Yes (warned)	No
Edge bend limit	Advisory	Maximum 2
Typical use case	Internal docs, drafts	Production, marketing

Summary

• standard is Archify's default, permissive quality profile that renders diagrams with advisory warnings for visual quality issues
• showcase enforces strict composition-quality rules from the Fireworks project, treating any violation as a fatal error
• Configure via --quality CLI flag in scripts/package-smoke.mjs or meta.quality_profile in your JSON source
• Both values are validated against the qualityProfile enum in archify/schemas/common.schema.json

Frequently Asked Questions

What happens if I omit the quality profile entirely?

Archify defaults to standard. Your diagram renders with quality warnings visible in logs, but no violations block output. This behavior is hardcoded in the renderer's default configuration.

Can I switch profiles without modifying my source files?

Yes. Use the --quality CLI flag to override any meta.quality_profile setting: archify render diagram.json --quality showcase forces strict validation regardless of the JSON content.

Does the showcase profile affect layout algorithms or just validation?

The showcase profile applies the same layout algorithms but enforces a stricter post-layout validation contract. It checks the rendered result against quality rules rather than changing how nodes are positioned. Violations mean the layout itself is rejected.

Where are the quality rules formally defined?

The composition-quality contract originates from Archify's Fireworks project and is referenced in docs/research-visual-evolution-round-44.md. The specific rules—no line crossings, bend limits, spacing minimums—are implemented in the renderer's validation layer, triggered when quality_profile equals "showcase".

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