Archify Quality Profiles Explained: Standard vs. Showcase Differences

Archify's standard and showcase quality profiles differ in how strictly they enforce composition rules—standard treats composition issues as warnings for iterative development, while showcase elevates them to hard errors for polished, public-facing artifacts.

When generating architectural diagrams in Archify, the quality_profile setting determines whether the renderer prioritizes development velocity or visual perfection. This guide breaks down the behavioral differences, exit semantics, and implementation details of each profile as defined in the tt-a1i/archify source code.

What Are Archify Quality Profiles?

Quality profiles in Archify are composition validation modes that control how the engine handles aesthetic violations in diagram layouts. The profile is specified per-render and stored in the composition receipt for auditability.

According to archify/schemas/architecture.schema.json at line 21, the valid values are strictly enumerated:

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

Standard Profile: Permissive Development Mode

The standard profile (default) is optimized for engineering workflows where diagrams evolve rapidly and visual perfection is secondary to functional correctness.

Validation Behavior

• Safety errors (edges through nodes, non-finite paths) → Hard failure
• Composition issues (proper crossings, unrelated overlaps, container-border runs) → Warning only

Exit Semantics

The CLI returns exit code 0 even when warnings are present. The artifact is still generated, and warnings are recorded in the receipt for later inspection.

# Default standard profile behavior

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

# Both exit 0 with warnings in receipt; artifact produced

This permissive approach lets developers iterate on dense, real-world diagrams without being blocked by every visual imperfection.

Showcase Profile: Strict Gallery Standard

The showcase profile is an opt-in strict mode for polished Gallery or README artifacts that represent the project to end-users.

Validation Behavior

• Safety errors → Hard failure (unchanged from standard)
• Composition errors → Hard failure for:
  • Proper interior X crossings
  • Unrelated collinear overlaps
  • Routes collinear with container borders

Exit Semantics

The CLI returns a non-zero exit code when any composition error is detected. The artifact is rejected and not produced for showcase generation.

# Strict showcase profile behavior

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

# Exits non-zero on composition errors; artifact rejected

Side-by-Side Comparison

Aspect	Standard Profile	Showcase Profile
Primary use case	Engineering diagrams, backward-compatible renders	Public Gallery/README artifacts
Proper crossing	Warning	Hard error
Unrelated overlap	Warning	Hard error (collinear only)
Container-border run	Warning	Hard error
CLI exit code	0 (with warnings)	Non-zero (with errors)
Artifact output	Always produced	Rejected on error

Implementation in Source Code

The behavioral differences are validated in archify/test/render-output-checks.test.mjs at lines 246–250. This test suite confirms that:

// Pseudocode based on test logic
test('proper crossing severity differs by profile', () => {
  const standardResult = render(diagram, { profile: 'standard' });
  assert(standardResult.warnings.includes('proper_crossing'));
  assert.strictEqual(standardResult.exitCode, 0);

  const showcaseResult = render(diagram, { profile: 'showcase' });
  assert(showcaseResult.errors.includes('proper_crossing'));
  assert.notStrictEqual(showcaseResult.exitCode, 0);
});

The design rationale is documented in docs/research-visual-evolution-round-44.md at the profile table (lines 48–53), which explicitly maps each profile to its intended audience and strictness level.

Checking Active Profile

To verify which profile applies to a validation run:

archify validate architecture diagram.json --json

The JSON output includes the active profile:

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

When to Use Each Profile

Use standard when:

• Rapidly iterating on complex diagrams
• Maintaining backward compatibility with existing renders
• Interior crossings are acceptable for clarity

Use showcase when:

• Generating official documentation assets
• Publishing to public Galleries or README files
• Visual polish reflects directly on project quality

Summary

• Standard is the default, developer-friendly mode that warns on composition issues without blocking output—ideal for everyday engineering workflows.
• Showcase enforces a strict visual standard by elevating composition warnings to hard errors, ensuring only polished artifacts reach end-users.
• Both profiles share identical safety validation; the divergence applies exclusively to aesthetic concerns.
• Profile behavior is schema-defined in architecture.schema.json, tested in render-output-checks.test.mjs, and documented in research-visual-evolution-round-44.md.

Frequently Asked Questions

How do I set the quality profile in Archify CLI?

Pass --quality <profile> to any render or validate command. Valid values are standard (default if omitted) or showcase. Example: archify render architecture diagram.json out.html --quality showcase.

Can I override the default standard profile globally?

No—Archify requires explicit per-command profile selection. This intentional design prevents accidental strictness changes in CI/CD pipelines where showcase failures would break automated builds.

What happens to warnings in standard mode—are they visible?

Yes. Warnings are captured in the composition receipt (JSON output) and printed to stderr, but they do not affect the exit code or prevent artifact generation. Use archify validate ... --json to inspect them programmatically.

Does showcase profile affect layout algorithms or just validation?

Only validation. Both profiles use identical layout engines; showcase simply applies stricter post-render checks. To improve layout quality, adjust diagram structure or routing parameters rather than switching profiles.

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