Archify Quality Profiles and Engineering Contracts Explained

Archify uses two primary quality profiles—standard and showcase—alongside formal engineering contracts to enforce strict visual guarantees and component interoperability in generated diagram artifacts.

The tt-a1i/archify repository implements a contract-backed design system that governs how diagrams are rendered, validated, and delivered. Understanding Archify quality profiles and engineering contracts is essential for teams that require reproducible, high-fidelity SVG artifacts with strict composition standards.

What Are Archify Quality Profiles?

Archify defines quality profiles as named configuration sets that determine how rendered diagrams are validated and what visual constraints they must satisfy. These profiles are selected via the CLI flag --quality standard|showcase and are reflected in the composition receipt attached to each SVG artifact.

The Standard Profile

The standard profile applies the default set of validation rules, providing balanced rendering suitable for most development workflows. When no --quality flag is specified, Archify automatically selects this profile.

The Showcase Profile

The showcase profile enforces a stricter composition-quality contract derived from the Fireworks Tech Graph. According to archify/references/composition-quality-contract.md, this profile guarantees zero line-crossings, no bridges, limited bends (maximum 2), and tighter spacing constraints (node spacing ≥32px, container gutter ≥16px).

Core Engineering Contracts

Beyond profiles, Archify establishes engineering contracts that formalize expectations between components, tools, and generated artifacts. These contracts ensure consistent validation rules and schema versions across the ecosystem.

Delivery Contract

Defined in archify/references/delivery-contract.md, the Delivery Contract specifies the schema for the composition receipt, the artifact checker, and required fields for each diagram including version, revision, and quality profile.

Authoring Contract

The Authoring Contract governs how diagram authoring modules expose their SemVer, field definitions, timestamps, and source URLs. This ensures consistent package metadata across different authoring tools, as detailed in archify/references/authoring-contract.md.

Composition-Quality Contract

As implemented in archify/references/composition-quality-contract.md, this contract outlines the visual quality metrics that the showcase profile must satisfy. The contract mandates specific pixel-based spacing requirements and topological constraints that the renderer must observe.

Cross-Renderer Contracts

Unified contracts for sequence, lifecycle, dataflow, and workflow renderers guarantee consistent validation rules across all renderer types. These shared contracts are documented in archify/renderers/README.md and ensure that schema versions remain synchronized regardless of output format.

Working with Quality Profiles and Validation

You can specify quality profiles during rendering and validate outputs against their declared contracts using the Archify CLI.

Render with the default standard profile:

archify render diagram.json --output diagram.svg

Render with the stricter showcase profile:

archify render diagram.json --quality showcase --output diagram-showcase.svg

Validate a rendered diagram against its declared contract:

archify validate diagram-showcase.svg --quality showcase

When using the showcase profile, Archify generates a composition receipt embedded in the SVG metadata. The receipt follows the schema defined in the delivery contract:

{
  "schemaVersion": "1.2",
  "revision": "a1b2c3d",
  "qualityProfile": "showcase",
  "checks": {
    "zeroCrossings": true,
    "noBridges": true,
    "maxBends": 2,
    "nodeSpacing": "≥32px",
    "containerGutter": "≥16px"
  },
  "status": "PASS"
}

Summary

• Archify provides two quality profiles: standard for default rendering and showcase for strict visual guarantees.
• The showcase profile enforces zero line-crossings, no bridges, and specific spacing constraints as defined in archify/references/composition-quality-contract.md.
• Engineering contracts formalize expectations through the Delivery, Authoring, and Cross-Renderer contracts documented in the archify/references/ directory.
• Use --quality showcase to opt into stricter validation and generate composition receipts that verify visual compliance against the defined contracts.

Frequently Asked Questions

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

The standard profile applies default validation rules suitable for general development, while the showcase profile enforces strict visual guarantees including zero line-crossings, no bridges, and limited bends as specified in archify/references/composition-quality-contract.md. The showcase profile is designed for presentations and production documentation where visual polish is critical.

How do I validate a diagram against its declared contract?

Use the archify validate command with the --quality flag matching your rendering profile, such as archify validate diagram-showcase.svg --quality showcase. This verifies compliance against the composition receipt schema defined in archify/references/delivery-contract.md and checks that all visual constraints are satisfied.

Where are the contract definitions documented?

Contract definitions reside in the archify/references/ directory, specifically delivery-contract.md for receipt schemas, authoring-contract.md for package metadata requirements, and composition-quality-contract.md for visual quality metrics. Additional renderer-specific contracts are documented in archify/renderers/README.md.

Can I create custom quality profiles?

Currently, Archify supports only the built-in standard and showcase profiles as documented in the repository's CHANGELOG.md. While the contract system is designed to be extensible, implementing custom quality profiles requires modifications to the core validation engine and contract schema definitions.

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