How to Configure Archify Quality Profiles: Standard vs Showcase

Use the --quality CLI flag or set quality_profile in your .architecture.json metadata to switch between the advisory-level standard profile and the strict, presentation-grade showcase profile.

Archify is an open-source diagram generation tool that uses quality profiles to enforce visual constraints during rendering. Understanding how to configure archify quality profiles allows you to optimize output for either rapid iteration or polished presentation. This guide explains the differences between the standard and showcase profiles and demonstrates how to apply them using CLI flags or JSON metadata.

Understanding Archify Quality Profiles

Archify provides two built-in quality profiles that control layout constraints and visual polish during diagram generation.

Standard Profile (Advisory)

The standard profile is the default setting, designed for internal drafts and rapid iteration. According to the tt-a1i/archify source code, this profile:

• Uses advisory quality gates (quality_gates: "advisory")
• Tolerates minor line crossings and bends
• Prioritizes layout flexibility over strict visual rules

Showcase Profile (Strict)

The showcase profile enforces presentation-grade constraints suitable for final deliverables. As implemented in the Archify rendering engine, this profile requires:

• Zero line crossings and no bridges
• Maximum of two bends per edge
• Minimum node spacing and container gutters
• Strict quality gates for polished documentation

How to Configure Quality Profiles

You can configure archify quality profiles through two methods: CLI arguments or metadata files.

Method 1: Command-Line Interface (CLI)

The fastest way to switch profiles is using the --quality flag when invoking Archify. This flag is parsed in scripts/package-smoke.mjs and overrides any metadata settings.

Standard (default):

archify generate --quality standard

Or omit the flag entirely.

Showcase (strict):

archify generate --quality showcase

Method 2: Metadata JSON Configuration

For persistent configuration, add the quality_profile property to any .architecture.json file within the meta object.

Example from archify/examples/checkout-platform.head.architecture.json:

{
  "meta": {
    "quality_profile": "showcase"
  }
}

The base example at archify/examples/checkout-platform.base.architecture.json uses "quality_profile": "standard" to demonstrate the default configuration.

Configuration Precedence

When both methods are present, the CLI flag takes precedence. As implemented in the CLI runner at scripts/package-smoke.mjs, the --quality flag overrides the meta.quality_profile value found in JSON files.

Practical Implementation Examples

CLI Usage

Generate diagrams with specific quality profiles directly from the terminal:

# Generate with standard profile for drafts

archify render diagrams/flowchart.svg

# Generate with showcase profile for presentations

archify render diagrams/flowchart.svg --quality showcase

JSON Metadata Configuration

Configure quality profiles permanently in your architecture definitions:

{
  "meta": {
    "title": "Production Architecture",
    "quality_profile": "showcase",
    "quality_gates": "strict"
  },
  "nodes": [],
  "edges": []
}

Programmatic Profile Switching

Automate quality profile selection in build scripts:

import { execSync } from "child_process";

function renderDiagram(profile) {
  execSync(`archify render src/diagram.architecture.json --quality ${profile}`);
}

// Draft version with standard profile
renderDiagram("standard");

// Polished version with showcase profile
renderDiagram("showcase");

Key Source Files and Implementation

The quality profile system is implemented across several key files in the tt-a1i/archify repository:

• scripts/package-smoke.mjs: CLI entry point that parses --quality arguments and handles profile overrides
• archify/examples/checkout-platform.base.architecture.json: Example using the standard profile
• archify/examples/checkout-platform.head.architecture.json: Example using the showcase profile
• docs/research-visual-evolution-round-44.md: Design documentation explaining the --quality flag behavior and its interaction with meta.quality_profile

Summary

• Archify provides two quality profiles: standard (advisory, default) and showcase (strict)
• Configure via CLI using --quality standard or --quality showcase
• Configure persistently via JSON using "quality_profile": "showcase" in the meta object
• CLI flags override JSON metadata settings according to the implementation in scripts/package-smoke.mjs
• Use standard for rapid iteration and showcase for presentation-grade diagrams with zero line crossings

Frequently Asked Questions

What is the difference between standard and showcase quality profiles in Archify?

The standard profile allows minor visual imperfections like line crossings and bends, making it ideal for drafts and internal documentation. The showcase profile enforces strict constraints including zero line crossings, no bridges, and maximum two bends per edge, producing publication-ready diagrams suitable for marketing assets and final deliverables.

Can I set a quality profile permanently for my project?

Yes. Add "quality_profile": "showcase" to the meta object in your .architecture.json file. This setting persists across renders unless overridden by the --quality CLI flag, allowing you to maintain consistent quality standards for specific architecture definitions.

Why does my CLI quality flag override my JSON configuration?

According to the implementation in scripts/package-smoke.mjs, command-line arguments take precedence over file metadata to allow temporary overrides without modifying source files. This enables quick switching between draft and production outputs using the same architecture definition.

Where can I see examples of both quality profiles in use?

The repository includes working examples at archify/examples/checkout-platform.base.architecture.json (standard profile) and archify/examples/checkout-platform.head.architecture.json (showcase profile). These files demonstrate real-world configuration patterns for each quality level.

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