Archify Deployment-Ownership Engineering Profile Validation: A Complete Guide

Archify performs fail-closed validation on authored JSON architecture diagrams to enforce strict ownership, region, and security rules before any deployment documentation can be published.

The deployment-ownership engineering profile validation system in Archify ensures that production deployment topologies are explicitly authored with complete ownership metadata and security boundaries. Unlike tools that discover infrastructure from live environments, Archify validates the static JSON Intermediate Representation (IR) to provide a trustworthy, reproducible proof of deployment topology. This validation is opt-in and implemented entirely within the tt-a1i/archify repository's rendering and testing pipeline.

How Deployment-Ownership Validation Works in Archify

The validation process operates through a strict seven-step pipeline that inspects the authored JSON IR before permitting diagram publication.

Enabling the Engineering Profile

To activate deployment-ownership engineering profile validation, authors must explicitly set the meta.engineering_profile field in their Architecture JSON. Archify treats this as an opt-in contract; the system only enforces ownership rules when the user explicitly requests a deployment review by setting the value to "deployment-ownership".

According to the source code in archify/schemas/architecture.schema.json (line 22), the schema defines a strict enum that accepts only ["deployment-ownership"] for this field. Any other value triggers immediate schema validation failure.

Schema Validation and Constraints

Once enabled, the JSON schema validates structural constraints before the engine processes the diagram. The schema ensures that the engineering_profile property contains only the accepted enum value, rejecting malformed declarations at the parsing stage.

Engine-Level Rule Enforcement

The core validation logic resides in archify/renderers/shared/engineering-profiles.mjs, where the constant DEPLOYMENT_PROFILE defines the rule set. The loader performs three critical checks on every non-external component:

• Ownership mandate: Every component must specify an owner field
• Region uniqueness: Each component must belong to exactly one region
• Database privacy: Database components must have private: true set

These rules are enforced during the validate phase, ensuring that incomplete or insecure topologies cannot proceed to delivery.

Fail-Closed Validation Behavior

Archify implements fail-closed semantics for the deployment-ownership profile. If any component violates the ownership, region, or privacy constraints, the validator emits structured machine-readable diagnostics and immediately aborts the delivery step.

Validation Receipts and Diagnostic Output

When running validation via the CLI, successful checks return a JSON receipt confirming the active profile. As verified in archify/test/engineering-profile.test.mjs (line 179), a passing validation returns:

{
  "engineeringProfile": "deployment-ownership",
  "validation": "passed"
}

If validation fails, the system outputs detailed diagnostics with specific error codes and component references. For example, a private database violation produces:

{
  "diagnostics": [
    {
      "code": "E001",
      "subject": "node:db",
      "message": "Database must be private in deployment-ownership profile."
    }
  ]
}

This structured output allows CI/CD pipelines to parse failures programmatically without inspecting log files.

HTML Artifacts and Proof Publication

Successfully validated diagrams receive permanent proof markers in the generated HTML. The SVG root element in the output file contains the attribute data-engineering-profile="deployment-ownership", as seen in docs/gallery/artifacts/production-deployment.architecture.html (line 4912).

This attribute serves two purposes: it marks the artifact as validated for human reviewers, and it enables downstream consumers to discover the profile programmatically when parsing the HTML. The validated diagram is then eligible for publication in the Gallery with the deployment-ownership tag.

Practical Implementation Guide

Implementing the deployment-ownership profile requires specific JSON structure and CLI commands.

Configuring the deployment-ownership Profile

Architecture JSON files must include the meta block and adhere to ownership constraints:

{
  "meta": {
    "engineering_profile": "deployment-ownership"
  },
  "nodes": [
    { 
      "id": "api", 
      "label": "API Server", 
      "owner": "Team-A", 
      "region": "us-east-1" 
    },
    { 
      "id": "db",  
      "label": "PostgreSQL",   
      "owner": "Team-B", 
      "region": "us-east-1", 
      "private": true 
    }
  ],
  "edges": [
    { "source": "api", "target": "db", "label": "SQL" }
  ]
}

Note that every node requires an owner and single region, while database nodes must include "private": true.

Validating Architecture JSON

Run the validation command to check compliance before delivery:

node archify/bin/archify.mjs validate architecture deployment.json --json

This command processes the JSON IR against the DEPLOYMENT_PROFILE ruleset in archify/renderers/shared/engineering-profiles.mjs and outputs either a success receipt or structured diagnostics.

Delivering Validated Diagrams

To generate the final HTML artifact with embedded validation proof:

node archify/bin/archify.mjs deliver architecture deployment.json ./deployment.html --open --json

If validation fails, this command aborts without overwriting existing artifacts, preserving the integrity of previously validated diagrams. Verify the embedded profile marker using:

grep -i 'data-engineering-profile' deployment.html

The output should confirm: <svg … data-engineering-profile="deployment-ownership">.

Summary

• Archify deployment-ownership engineering profile validation is an opt-in, fail-closed system that validates JSON IR before publication
• Enforcement occurs in archify/renderers/shared/engineering-profiles.mjs via the DEPLOYMENT_PROFILE constant
• Validation requires explicit ownership, single-region assignment, and database privacy for all non-external components
• Successful validation embeds data-engineering-profile="deployment-ownership" in the SVG root for programmatic discovery
• Failures produce structured JSON diagnostics and abort delivery, preventing invalid topologies from reaching production documentation

Frequently Asked Questions

What triggers the deployment-ownership validation in Archify?

The validation triggers when the meta.engineering_profile field is set to "deployment-ownership" in the Architecture JSON. This explicit opt-in mechanism, documented in archify/SKILL.md (line 74), ensures that strict ownership rules only apply when authors intentionally request deployment review.

How does Archify handle validation failures?

Archify implements fail-closed behavior: validation failures emit machine-readable JSON diagnostics and immediately abort the delivery step. The system preserves existing validated artifacts rather than publishing incomplete or non-compliant diagrams, ensuring that only fully compliant topologies reach the Gallery.

Where is the engineering profile stored in the output HTML?

The validated profile is stored in the data-engineering-profile attribute on the SVG root element within the generated HTML file. This marker appears in files like docs/gallery/artifacts/production-deployment.architecture.html and allows automated systems to verify validation status without parsing JSON receipts.

What files define the deployment-ownership rule set?

The rule set is defined across three primary files: archify/schemas/architecture.schema.json constrains valid profile values, archify/renderers/shared/engineering-profiles.mjs implements the ownership and privacy logic, and docs/deployment-ownership-profile-acceptance-2026-07-23.md documents the formal acceptance criteria and gating rules for production deployments.

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