What Is Archify's Deployment Ownership Validation Contract?

Archify's deployment ownership validation contract is a schema-driven guarantee that ensures architecture diagrams explicitly declare workload ownership, document named crossing points, and provide operational evidence through a machine-validated receipt format.

The tt-a1i/archify repository treats deployment ownership as a first-class semantic profile that can be automatically verified by the platform. This contract ensures that production architecture diagrams meet strict engineering standards regarding accountability and operational transparency before they are accepted into the system.

Core Components of the Validation Contract

The deployment ownership validation contract consists of three complementary parts that work together to enforce compliance.

Engineering Profile Tag

Every architecture diagram that participates in the contract must carry the "engineering_profile": "deployment-ownership" flag in its metadata. This tag tells Archify to apply the deployment-ownership verification rules during validation.

In docs/gallery/sources/production-deployment.architecture.json, the profile is declared within the meta object:

{
  "meta": {
    "title": "Production Deployment Ownership",
    "engineering_profile": "deployment-ownership",
    "views": [
      { "id": "request-boundary", "label": "Request crosses the edge" },
      { "id": "state-ownership", "label": "State and ownership" },
      { "id": "async-operations", "label": "Async and operations" }
    ]
  }
}

Receipt Format

A receipt is a JSON document produced after a diagram is rendered. To satisfy the contract, the receipt must contain an engineeringProfile field set to "deployment-ownership" and must be generated by a successful validate --json (or deliver --json) run.

The receipt proves that the diagram's components, boundaries, and crossings have been checked against the contract's expectations. When validation passes, the receipt includes a status: "passed" field along with a summary of validated elements.

Schema Validation

Archify validates the receipt against the architecture schema located at archify/schemas/architecture.schema.json. The schema enforces constraints that require:

• The presence of the engineering_profile tag
• The correct structure of components, boundaries, and connections
• The existence of three mandatory guided-view sections: request-boundary, state-ownership, and async-operations

When the receipt conforms to these structural rules, the contract is considered passed.

Contract Guarantees and Requirements

The validation contract guarantees that a deployment diagram satisfies three critical operational requirements:

1. Explicit ownership declaration — Every workload must declare its owner (platform team, app team, data team, etc.)
2. Named crossing points — The diagram must document specific transition points (e.g., public HTTPS → edge, mTLS → private network, cross-region WAL)
3. Operational evidence — The structure must support tracing audit logs and observability traces back to specific owners

If any of these elements is missing or malformed, receipt validation fails and the diagram is rejected until the contract is satisfied.

Practical Implementation Examples

Creating a Deployment-Ownership Diagram

To define a compliant architecture diagram, create a JSON file following the structure found in archify/examples/production-deployment.architecture.json:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Production Deployment Ownership",
    "engineering_profile": "deployment-ownership",
    "views": [
      { "id": "request-boundary", "label": "Request crosses the edge", "focus": ["clients","edge","gateway","api_a","api_b"] },
      { "id": "state-ownership",  "label": "State and ownership", "focus": ["api_a","api_b","redis","postgres","replica"] },
      { "id": "async-operations", "label": "Async and operations", "focus": ["api_b","events","worker","audit","observability"] }
    ]
  },
  "components": [
    { "id": "clients", "type": "external", "label": "Customers", "tag": "none" },
    { "id": "edge", "type": "cloud", "label": "Global Edge", "tag": "edge team" }
  ],
  "boundaries": [],
  "connections": [],
  "cards": []
}

Generating Validation Receipts via CLI

Use the Archify CLI (defined in archify/package.json) to validate diagrams and produce receipts:

# Run Archify's validator on the diagram file

archify validate --json examples/production-deployment.architecture.json

This command outputs a receipt document:

{
  "engineeringProfile": "deployment-ownership",
  "status": "passed",
  "generatedAt": "2026-08-09T12:34:56Z",
  "summary": {
    "components": 12,
    "boundaries": 4,
    "connections": 9
  }
}

Programmatic Contract Verification

You can validate receipts programmatically using JSON Schema validation libraries:

import fs from 'fs';
import Ajv from 'ajv';
import schema from './archify/schemas/architecture.schema.json';

const receipt = JSON.parse(fs.readFileSync('receipt.json'));

// Quick contract check
if (receipt.engineeringProfile !== 'deployment-ownership') {
  throw new Error('Receipt does not claim deployment-ownership profile');
}

// Full JSON-Schema validation
const ajv = new Ajv();
const validate = ajv.compile(schema);
if (!validate(receipt)) {
  console.error(validate.errors);
  throw new Error('Receipt fails architecture schema validation');
}
console.log('Deployment-ownership contract satisfied ✅');

Summary

• The deployment ownership validation contract requires the engineering_profile tag set to "deployment-ownership" in diagram metadata
• Validation produces a machine-readable receipt that proves compliance with ownership, boundary, and operational evidence requirements
• The contract enforces three specific guided views: request-boundary, state-ownership, and async-operations
• Schema validation occurs against archify/schemas/architecture.schema.json, which structurally enforces all contract rules
• CLI commands validate --json and deliver --json generate the required receipt documents

Frequently Asked Questions

What happens if the deployment ownership validation fails?

If validation fails, Archify rejects the diagram and returns an error indicating which contract requirement was violated. This could include missing ownership tags, absent guided-view sections, or structural schema violations. The diagram must be corrected and resubmitted until the receipt shows "status": "passed".

How does the engineering profile tag activate the contract?

The "engineering_profile": "deployment-ownership" flag in the diagram's meta object acts as a semantic switch. When Archify's validator encounters this flag, it applies the specific deployment-ownership rules rather than generic validation, checking for the three mandatory guided views and ownership declarations.

Can I validate deployment ownership contracts programmatically?

Yes. As shown in the Node.js example, you can programmatically validate receipts by checking the engineeringProfile field value and running JSON Schema validation against archify/schemas/architecture.schema.json. This allows integration into CI/CD pipelines or custom tooling.

Where are the canonical examples and schemas located?

The canonical diagram example resides in docs/gallery/sources/production-deployment.architecture.json, while runnable examples are stored in archify/examples/production-deployment.architecture.json. The validation schema is defined in archify/schemas/architecture.schema.json, and the CLI entry point is configured in archify/package.json.

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