What Does the Architecture Delta Comparison Receipt Contain? Complete JSON Structure Guide

The architecture delta comparison receipt is a JSON-encoded artifact that records the complete structural difference between two architecture model versions, containing metadata fields, high-level change summaries, detailed listings of modified components/connections/boundaries, identity mappings, visualization hints, cryptographic fingerprints, and validation outcomes.

The architecture delta comparison receipt is the primary output of the comparison engine in the tt-a1i/archify repository. Stored at examples/checkout-platform-delta.receipt.json, this machine-readable artifact provides a deterministic audit trail of how a baseline architecture model differs from a new head version, enabling downstream CI pipelines, visualizers, and governance tools to process architectural changes programmatically.

Core Metadata and Versioning Fields

Every receipt begins with standard metadata that identifies the schema, operation, and comparison engine characteristics.

• schemaVersion: An integer defining the receipt schema version (e.g., 1).
• ok: A boolean flag indicating overall comparison success.
• command: The operation that produced the receipt, typically "compare".
• type: The artifact classification, set to "architecture" for delta comparisons.
• comparatorVersion: Version identifier of the comparison engine that generated the receipt.
• canonicalVersion: Version of the canonical internal representation used during comparison.
• completeness: Indicates coverage scope, typically "complete" when the full model was analyzed.
• proofLevel: Trust level of the generated intermediate representation, such as "authored".

Base and Head Model References

The receipt contains base and head objects that cryptographically identify the two compared architecture versions. Each block includes:

• Title: Human-readable description (e.g., "Checkout Platform — Baseline" vs "Checkout Platform — Fraud Gate").
• Raw and Semantic Hashes: SHA-256 fingerprints of the raw input and semantic model.
• Byte Size: The total size of the underlying artifact.

As seen in examples/checkout-platform-delta.receipt.json, these fields allow consumers to verify exactly which revisions were compared and ensure artifact integrity.

High-Level Change Summaries

The summary field provides aggregate counts of architectural modifications, organized by element type:

• Components: Counts of added, changed, removed, and moved elements.
• Connections: Tallies for added, changed, removed, and rerouted links between components.
• Boundaries: Counts of added, changed, or removed containment boundaries.

This section also flags presentation and provenance changes that might affect rendering or audit trails without altering structural topology.

Detailed Change Listings

The changes object contains granular arrays documenting every specific modification.

Component Changes

Stored in changes.components, each entry is an object with:

• id: Unique component identifier.
• status: One of added, removed, changed, or moved.
• Base and Head Labels: The display names in each version.
• Classification Tags: Categorical metadata for filtering.
• Changed Fields: Specific JSON Pointer paths that differ (e.g., "/sublabel" for label modifications or "/pos" for positional moves).

For example, the receipt shows component "checkout" with status: "changed" modifying the "/sublabel" field, while component "queue" records status: "moved" with changes to "/pos".

Connection Changes

The changes.connections array tracks edge modifications between components. Each object includes:

• id: Connection identifier.
• Endpoint Definitions: from, to, label values for both base and head versions.
• status: added, changed, removed, or rerouted.
• Field Diffs: Specific attributes that changed, such as fromSide, toSide, or via routing coordinates.

In the sample receipt, connection "authorize-payment" shows changes to from, fromSide, toSide, and via fields, while "fraud-check" appears as a newly added connection.

Boundary Changes

Stored in changes.boundaries, these objects describe containment modifications:

• key: Unique boundary identifier (e.g., "region:Production region").
• kind: Boundary classification type.
• label: Human-readable description.
• status: Modification state.
• Changed Fields: Specific structural modifications, such as updates to "/wraps" indicating different contained elements.

Identity Mappings and Visualization

Identity Resolution

The identity field maps receipt identifiers back to underlying model elements, specifying lookup paths for components, connections, and boundaries. This ensures that visualizers and analysis tools can correlate receipt entries with source architecture artifacts.

Visualization Preferences

The view object suggests rendering presets for delta visualization tools. For example, "visualPreset": "signal-flow" indicates the recommended diagram type for displaying the changes, helping tools like C4-PlantUML or Structurizr select appropriate layouts automatically.

Limitations, Provenance, and Validation

Limitations

The limitations array explicitly declares what the receipt does not infer. According to the schema implemented in tt-a1i/archify, these declarations include:

• No runtime impact assessment.
• No causality determination between changes.
• No risk scoring or security analysis.
• No mergeability guarantees for the proposed changes.

These boundaries prevent automated systems from over-interpreting static structural differences as behavioral or deployment-safe modifications.

Artifact Provenance

The artifact field provides a cryptographic fingerprint (SHA-256 hash) and byte size of the compared architecture file, enabling reproducibility verification. For instance, the sample receipt records SHA-256 b1a9… with a size of 1 836 089 bytes.

Validation Outcomes

The validation object reports internal consistency checks:

• Passed Checks: Count of successful validations (e.g., 28 passed).
• Total Checks: Total number of validation rules executed.
• Composition Status: Pass/fail indicators for both base and head model compositions.

This section confirms that the compared models were structurally sound before delta calculation began.

Parsing the Architecture Delta Comparison Receipt

The following examples demonstrate how to extract specific insights from the receipt file using JavaScript and Python.

JavaScript (Node.js)

const fs = require('fs');

// Load the receipt JSON
const receipt = JSON.parse(fs.readFileSync(
  'examples/checkout-platform-delta.receipt.json',
  'utf8'
));

// List all changed components (excluding additions and removals)
const changedComponents = receipt.changes.components.filter(
  c => c.status !== 'added' && c.status !== 'removed'
);
console.log('Changed components:', changedComponents.map(c => c.id));

// Summarize connection changes
const conn = receipt.summary.connections;
console.log(
  'Connection changes → added:', conn.added,
  'changed:', conn.changed,
  'removed:', conn.removed,
  'rerouted:', conn.rerouted
);

Python

import json

with open('examples/checkout-platform-delta.receipt.json') as f:
    receipt = json.load(f)

# Print high-level component summary

summary = receipt['summary']
print(
    'Components – added:', summary['components']['added'],
    'changed:', summary['components']['changed'],
    'removed:', summary['components']['removed'],
    'moved:', summary['components']['moved']
)

# Extract all newly added connections

added_conns = [
    c for c in receipt['changes']['connections']
    if c['status'] == 'added'
]
print('New connections:', [c['id'] for c in added_conns])

These snippets demonstrate filtering specific change types and generating stakeholder reports from the machine-readable structure.

Summary

• The architecture delta comparison receipt is a versioned JSON artifact produced by the tt-a1i/archify comparison engine.
• It contains base and head metadata with SHA-256 hashes identifying the compared versions.
• The summary field provides aggregate counts of component, connection, and boundary changes.
• Detailed modifications are listed in changes.components, changes.connections, and changes.boundaries, including specific field paths via JSON Pointer notation.
• The identity field maps receipt IDs to model elements, while view suggests visualization presets.
• limitations explicitly excludes runtime impact, causality, and mergeability assessments.
• validation reports internal consistency check results, ensuring model integrity.

Frequently Asked Questions

What file format does the architecture delta comparison receipt use?

The receipt uses standard JSON encoding with a defined schema version (indicated by the schemaVersion field). This format ensures broad interoperability with JavaScript, Python, Go, and other languages commonly used in CI/CD pipelines.

How does the receipt distinguish between a moved component and a changed component?

The receipt uses the status field within changes.components entries. A "moved" status indicates positional changes (typically tracked in the "/pos" field), while "changed" indicates modifications to non-positional attributes like labels, types, or metadata (tracked in fields like "/sublabel").

Can the architecture delta comparison receipt determine if changes are safe to deploy?

No. The limitations field explicitly states that the receipt represents "Authored Architecture IR only" and does not infer runtime impact, risk, or mergeability. Consumers must implement separate safety checks; the receipt only provides the structural delta for analysis.

Where can I find an example of a complete architecture delta comparison receipt?

The repository contains a fully populated example at examples/checkout-platform-delta.receipt.json. This file demonstrates all top-level fields including metadata, summaries, detailed change listings, and validation results as implemented in the tt-a1i/archify codebase.

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