How Does the `meta.quality_profile` Setting Affect Archify Diagram Generation?

The meta.quality_profile setting in Archify controls which visual and layout preset is applied during diagram generation, determining rendering precision, styling richness, and export fidelity.

Archify uses a quality profile—specified either via the --quality CLI flag or the meta.quality_profile field in your JSON input—to configure how much computational effort the engine invests in layout refinement and visual polish. This setting directly influences the trade-off between generation speed and output quality for architecture diagrams.

What meta.quality_profile Configures

When you set a quality profile, Archify applies a predefined bundle of rendering parameters. The profile affects four primary dimensions:

• Layout precision – Stricter convergence criteria for the deterministic layout engine, yielding fewer overlapping edges and more balanced node spacing
• Styling richness – Enables shadows, gradients, and richer label typography that are stripped out in lower-quality modes
• Animation behavior – Some profiles activate animated tracing (meta.animation = "trace"), while others disable motion for static export
• Export fidelity – Determines resolution, format options (PNG, SVG, WebM), and whether share-card graphics are generated

Setting Quality Profile via CLI

The most common way to specify a quality profile is through the --quality flag when invoking archify.mjs. This flag populates meta.quality_profile in the internal intermediate representation (IR).

# Generate a polished, presentation-ready diagram

node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json

# Use minimal quality for rapid iteration (default behavior)

node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json

In the archify/bin/archify.mjs entry point, the --quality argument is parsed and injected into the document's metadata structure before validation and rendering occur.

Setting Quality Profile in JSON Input

You can also embed the quality profile directly in your diagram specification. The meta object accepts quality_profile alongside other configuration keys like locale, animation, and visual_preset.

{
  "meta": {
    "locale": "en",
    "visual_preset": "signal-flow",
    "animation": "trace",
    "quality_profile": "showcase"
  },
  "nodes": [
    { "id": "api-gateway", "type": "service", "label": "API Gateway" }
  ],
  "edges": [
    { "from": "client", "to": "api-gateway", "type": "request" }
  ]
}

Available Quality Profiles

Archify recognizes profile names such as:

Profile	Use Case	Characteristics
showcase	Presentations, documentation	Maximum layout refinement, full styling, animation enabled, high-resolution exports
baseline	Development, CI/CD pipelines	Fast rendering, minimal styling, static output, reduced resolution

When meta.quality_profile is omitted, Archify defaults to a baseline-equivalent configuration prioritizing speed over polish.

How Quality Profile Propagates Through the Pipeline

1. CLI parsing – archify/bin/archify.mjs extracts --quality <profile> and merges it into document metadata
2. Schema validation – The meta object is validated against archify/schemas/architecture.json, which permits an optional quality_profile field
3. IR construction – The validated quality profile is embedded in the intermediate representation
4. Layout engine – The profile selects convergence thresholds and optimization passes for node positioning
5. Render stage – Visual features and export parameters are applied based on the active profile

Performance Implications

Choosing a quality profile involves measurable trade-offs:

• Showcase profiles may increase generation time by 3–5× due to additional layout iterations and post-processing effects
• Baseline profiles complete in sub-second times for diagrams with fewer than 100 nodes
• Memory usage scales with profile quality due to larger offscreen buffers for shadow and gradient compositing

For iterative workflows, omit --quality or explicitly use --quality baseline. For final artifacts committed to documentation or shared with stakeholders, --quality showcase ensures maximum visual impact.

Summary

• meta.quality_profile selects a bundled configuration of layout precision, styling, animation, and export parameters
• Set via --quality <profile> CLI flag or directly in JSON meta object
• showcase prioritizes visual fidelity at computational cost; baseline (default) prioritizes speed
• Defined in archify/schemas/architecture.json, processed through archify/bin/archify.mjs
• Omission triggers default fast-rendering behavior suitable for development cycles

Frequently Asked Questions

What happens if I specify both --quality CLI flag and meta.quality_profile in my JSON?

The CLI flag takes precedence. Archify merges command-line arguments after parsing the input file, so explicitly passing --quality showcase will override any quality_profile value present in the source JSON.

Can I define custom quality profiles beyond showcase and baseline?

The repository's schema structure in archify/schemas/architecture.json supports extensible profile names as strings. While the built-in engine recognizes standard profiles, you can pass arbitrary profile identifiers—the rendering pipeline will apply defaults for unrecognized profiles and log a warning.

Does quality_profile affect validation strictness or only rendering?

The quality profile influences rendering and export only. Schema validation in Archify is deterministic and does not vary with quality settings. A diagram that validates under baseline will validate identically under showcase; only the generated visual output differs.

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