Understanding the Quality Profiles for Archify Diagrams: A Complete Guide

Archify provides two distinct quality profiles—standard** and showcase—that control how strictly diagram composition is validated, with standard permitting warnings for drafts and showcase enforcing hard errors for production artifacts.**

The tt-a1i/archify repository implements these profiles to support different stages of diagram creation, from early exploratory sketches to polished, publication-ready visualizations. Understanding when to apply each quality profile for Archify diagrams ensures your documentation pipeline handles drafts permissively while maintaining strict quality gates for final deliverables.

What Are Quality Profiles in Archify?

Quality profiles in Archify are named configuration sets that determine validation behavior and visual rendering constraints. Stored in the meta.quality_profile field of your workflow files, these profiles dictate whether composition issues generate warnings or fatal errors.

According to generated/maka-regenerated.workflow.json, the schema accepts exactly two string values: "standard" and "showcase"【7†source】. This binary approach simplifies decision-making while providing clear separation between development and production states.

The Standard Quality Profile

The standard profile serves as the default fallback when no meta.quality_profile is explicitly set. As documented in archify/test/workflow-migration.test.mjs, this profile defaults to standard to accommodate iterative development workflows【388†source】.

Key characteristics:

• Validation behavior: Composition issues surface as warnings rather than errors
• CLI exit status: Process exits with success (0) despite visual imperfections
• Use cases: Exploratory work, early-stage drafts, and internal documentation where strict visual constraints are unnecessary

The examples/maka-architecture.html file demonstrates this profile in practice, using the attribute data-quality-profile="standard" on the SVG element【5008†source】.

The Showcase Quality Profile

The showcase profile targets polished, production-ready artifacts intended for public presentation or repository commits. The docs/authoring-cookbook.md explicitly recommends this profile "for a polished artifact" after using standard during exploration【58†source】.

Key characteristics:

• Validation behavior: Any composition violation triggers a hard error
• Visual constraints: Enforces tight budgets including zero line crossings, limited bends, and minimum node spacing
• CLI exit status: Non-zero exit code when validation fails, suitable for CI/CD quality gates
• Use cases: Final deliverables, proof-of-concepts checked into version control, and public presentations

You can observe this implementation in examples/web-app.html, which declares data-quality-profile="showcase" on its SVG output【5007†source】.

How to Configure Quality Profiles

Archify provides three methods for setting quality profiles: embedded metadata, CLI overrides, and programmatic configuration.

Workflow Metadata

Define the profile directly in your workflow JSON file:

{
  "meta": {
    "title": "Customer checkout flow",
    "quality_profile": "showcase"
  }
}

CLI Override

Override any embedded profile using the --quality flag, as tested in archify/test/workflow-migration.test.mjs:

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

This command-line option allows CI pipelines to enforce showcase standards regardless of what individual authors specified in their metadata.

Working with Quality Profiles Programmatically

When generating diagrams via the JavaScript API, pass the qualityProfile option to compileWorkflow:

// Setting the profile programmatically when generating a diagram
const diagram = compileWorkflow({
  workflow: myWorkflow,
  qualityProfile: 'showcase'   // or 'standard'
});

This approach integrates with build tools that dynamically adjust quality requirements based on deployment targets.

Summary

• Archify supports exactly two quality profiles for Archify diagrams: standard and showcase.
• standard is the default behavior, treating composition issues as warnings suitable for drafts.
• showcase enforces strict validation with fatal errors, ensuring production-ready output.
• Configure profiles via meta.quality_profile in JSON files, --quality CLI flags, or the qualityProfile API option.
• Source references including archify/test/workflow-migration.test.mjs and docs/authoring-cookbook.md confirm these behaviors are intentional design decisions for different workflow stages.

Frequently Asked Questions

What is the default quality profile in Archify?

Standard is the default quality profile when the meta.quality_profile field is omitted from your workflow file. According to archify/test/workflow-migration.test.mjs, the system automatically falls back to standard to support permissive, iterative development workflows without breaking builds【388†source】.

How do I override the quality profile from the command line?

Use the --quality flag followed by either standard or showcase. This CLI override takes precedence over any embedded metadata settings, allowing DevOps pipelines to enforce strict validation regardless of individual file configurations.

What happens when a showcase profile diagram has composition errors?

The rendering fails with a non-zero exit status. Unlike the standard profile which logs warnings and continues, showcase treats all composition violations—such as line crossings or insufficient node spacing—as fatal errors that halt the build process.

Can I set the quality profile programmatically?

Yes. When calling compileWorkflow() in JavaScript, pass the qualityProfile property in your options object with either 'standard' or 'showcase' as the value. This integrates quality controls directly into automated generation scripts and build pipelines.

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