Understanding the Engineering Profile for Archify Architecture Diagrams

The engineering profile is a metadata marker that activates domain-specific validation rules for Archify architecture diagrams, with the built-in deployment-ownership profile enforcing strict ownership tags and boundary constraints during the rendering pipeline.

Archify is an open-source diagramming framework that attaches specialized validation logic to architecture diagrams through engineering profiles. These profiles ensure deployment-related concerns are explicitly captured in diagram metadata before rendering. When the engineering_profile field is set in a diagram's metadata, the CLI triggers additional diagnostic checks beyond standard schema validation.

What Is the Engineering Profile?

The engineering profile is a declarative configuration option defined in a diagram's meta object that instructs Archify to run extra, domain-specific validation rules. Currently, Archify supports one built-in profile: deployment-ownership, defined as a constant in archify/renderers/shared/engineering-profiles.mjs.

When enabled, the profile acts as a contract between the diagram author and the rendering pipeline. The validateEngineeringProfile function (invoked from archify/renderers/shared/cli.mjs) forwards the diagram to specialized diagnostic handlers that verify architectural constraints before SVG generation begins.

The Deployment-Ownership Profile Validation Rules

The deployment-ownership profile enforces five specific constraints on architecture diagrams to ensure proper ownership attribution and security boundary compliance:

• Regional boundaries required: At least one region boundary and one security-group boundary must exist in the diagram.
• Ownership tags mandatory: Every non-external component must declare a non-empty tag field identifying its owner (e.g., "team-frontend").
• Single region assignment: Each component must belong to exactly one region boundary.
• Stateful component isolation: Stateful components (such as database types) must reside within a private security-group boundary.
• Cross-boundary documentation: Any connection crossing boundary lines must include a label describing the connection mechanism.

If validation fails, the CLI throws a diagnostic error and halts the rendering process. When validation passes, the CLI injects a data-engineering-profile attribute into the generated SVG root element.

How to Enable the Engineering Profile

To activate validation, add the engineering_profile key to your diagram's metadata object:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "My Service",
    "subtitle": "Deployment ownership view",
    "engineering_profile": "deployment-ownership"
  },
  "components": [
    { "id": "api", "type": "backend", "label": "API", "tag": "team-frontend" }
  ],
  "boundaries": [
    { "kind": "region", "label": "us-east-1", "wraps": ["api"] },
    { "kind": "security-group", "label": "private-db", "wraps": [] }
  ],
  "connections": []
}

The meta.engineering_profile field must exactly match the string "deployment-ownership" to trigger the validation logic defined in deploymentOwnershipDiagnostics.

CLI Rendering and SVG Output

The CLI integration propagates the engineering profile through to the rendered output. In archify/renderers/shared/cli.mjs, the svgRootAttrs function conditionally adds a data attribute to the SVG root:

export function svgRootAttrs(meta) {
  const engineeringProfile = meta.engineering_profile
    ? ` data-engineering-profile="${esc(meta.engineering_profile)}"`
    : '';
  // …other attrs omitted for brevity
  return `role="img"${engineeringProfile} …`;
}

This implementation ensures that rendered HTML artifacts (such as docs/gallery/artifacts/production-deployment.architecture.html) contain the data-engineering-profile="deployment-ownership" attribute, allowing downstream tooling to identify which validation rules were applied during generation.

To render a diagram with profile validation enabled, execute:

node archify/renderers/architecture/render-architecture.mjs examples/archify-repo.architecture.json out.html

If any validation rule fails, the process exits with a diagnostic error before writing the output file.

Summary

• The engineering profile activates domain-specific validation for Archify architecture diagrams through the meta.engineering_profile field.
• The only built-in profile is deployment-ownership, defined in archify/renderers/shared/engineering-profiles.mjs.
• Validation enforces ownership tags, regional boundaries, and security-group compliance via the deploymentOwnershipDiagnostics function.
• The CLI adds a data-engineering-profile attribute to generated SVGs when validation passes, traceable in the svgRootAttrs implementation.

Frequently Asked Questions

What values can the engineering_profile field contain?

Currently, Archify only supports the value "deployment-ownership" for architecture diagrams. This constant is exported as DEPLOYMENT_PROFILE from archify/renderers/shared/engineering-profiles.mjs. Setting any other value will not trigger validation logic in the current implementation.

How does the deployment-ownership profile detect missing owner tags?

The deploymentOwnershipDiagnostics function iterates through all components in the diagram JSON and checks for the presence of a non-empty tag property on every non-external component. Components without this field fail validation and trigger a diagnostic error before SVG rendering begins.

Where can I inspect the engineering profile in rendered output?

The rendered SVG element includes a data-engineering-profile attribute when validation is enabled. You can view this in the HTML source of generated artifacts (such as docs/gallery/artifacts/production-deployment.architecture.html) or by inspecting the SVG root element in browser developer tools.

What happens if validation fails during CLI rendering?

If validateEngineeringProfile detects a violation of the deployment-ownership rules (such as missing regions or untagged components), the CLI throws a diagnostic error and exits with a non-zero status code. The output HTML file is not generated until all validation constraints are satisfied.

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