How Archify Ensures Trust in Generated Diagrams: 6 Technical Mechanisms

Archify ensures trust in generated diagrams by anchoring every visual element to verifiable repository artifacts, enforcing explicit trust boundaries, and validating evidence before rendering.

Archify is an open-source architecture visualization tool (tt-a1i/archify) that produces diagrams from codebase analysis. Unlike generic drawing tools, Archify establishes trust in generated diagrams by binding every visual component to concrete, auditable evidence within your repository, starting with the tagline "you can trust" in docs/index.html and extending through cryptographic build verification.

Establishing Trust in Generated Diagrams Through Explicit Boundaries

Archify models security posture directly in the diagram structure. In examples/maka-architecture.html, trust boundaries are encoded as security groups within the architecture JSON. These frames render with distinct visual styling via SVG metadata attributes like data-composition-frame-kind="security-group".

The system defines these boundaries in the architecture configuration:

{
  "id": "system-overview",
  "type": "architecture",
  "diagram": [
    {
      "label": "trust boundary",
      "kind": "security-group",
      "elements": [ "permission", "storage", "api-gateway" ]
    }
  ]
}

This approach ensures that trust zones are not just visual suggestions but structural constraints enforced by the rendering engine. According to the tt-a1i/archify source code, these boundaries prevent unauthorized components from appearing within critical security perimeters.

Supply Chain Integrity and Trust in Generated Diagrams

Archify protects against supply chain attacks by validating update sources and build artifacts before distribution.

Verified Release Manifests

The system only accepts update manifests pointing to fixed, canonical GitHub Pages resources. As implemented in archify/test/update-notifier.test.mjs, the test suite enforces that production manifest URLs match a strict trusted pattern:

// Test that only a fixed, trusted manifest URL can be used for production updates
test('production manifest URL is a fixed trusted GitHub Pages resource', () => {
  const url = getManifestUrl();
  expect(url).toMatch(/^https:\/\/tt-a1i\.github\.io\/archify\/.*\.json$/);
});

This prevents malicious manifest injection by ensuring the URL is hardcoded to the official tt-a1i.github.io/archify/ domain.

Deterministic Build Signatures

The build pipeline produces a cryptographically verifiable artifact. The scripts/build-zip.sh script generates a deterministic ZIP archive (archify.zip) and records its hash. During release, this hash is compared against the recorded metadata; any mismatch aborts the publish process.

This guarantees that the diagram you see in production is exactly the one built from the source code, with no intermediate tampering. The archify/migrations/workflow-v2.mjs file preserves these trusted artifact signatures when migrating older workflow definitions.

Evidence-Based Validation for Trusted Diagrams

Archify validates node provenance before rendering, refusing to fabricate data when evidence is missing.

Repository Evidence Verification

Before rendering any diagram, Archify verifies that each node's attributes—such as component ownership and external dependencies—are backed by repository evidence. Source files, configuration entries, or explicit annotations serve as the ground truth. When evidence is missing, the system displays an unknown badge rather than inferring or inventing relationships.

Fail-Closed Security Model

Nodes belonging to security-critical groups implement fail-closed semantics. If trust validation fails for these nodes, Archify omits or de-emphasizes them in the final render, as seen in the node definitions at examples/maka-architecture.html#L5147. This prevents accidental exposure of insecure information when validation checks fail.

User-Facing Trust Indicators in Generated Diagrams

Archify surfaces trust status directly in the user interface. In docs/start.html, the system displays a green "✓" trust line when the description alone contains sufficient verified information to generate a diagram:

<!-- Trust line shown on the start page – confirms a minimal description is enough -->
<div class="trust-line"
     data-en="Your description is enough to make the first diagram."
     data-zh="只有一段描述，也足够画出第一张图。">
  Your description is enough to make the first diagram.
</div>

This visual indicator reinforces that the diagram is grounded in verified input rather than speculative generation.

Summary

• Explicit trust boundaries are encoded as security groups in architecture JSON and rendered via SVG metadata attributes.
• Deterministic builds in scripts/build-zip.sh produce verifiable artifacts with recorded hashes that abort publishing if tampered.
• Manifest verification tests in update-notifier.test.mjs enforce hardcoded GitHub Pages URLs to prevent supply chain attacks.
• Evidence-based rendering validates node provenance against repository files, displaying "unknown" badges when verification fails.
• Fail-closed semantics automatically omit security-critical nodes when validation fails, preventing information leakage.
• Trust indicators in the UI provide immediate visual confirmation that diagrams are built from verified descriptions.

Frequently Asked Questions

How does Archify prevent unauthorized updates to diagram definitions?

Archify validates all update manifests against a hardcoded, trusted GitHub Pages URL pattern enforced in archify/test/update-notifier.test.mjs. The system rejects any manifest that does not originate from the official tt-a1i.github.io/archify/ domain, preventing supply chain attacks through malicious update sources.

What happens when Archify cannot verify a component's origin?

When node provenance cannot be verified against repository evidence, Archify displays an unknown badge rather than fabricating data. This fail-strict approach ensures that diagrams never present speculative information as factual architecture.

How are trust boundaries visually represented in Archify diagrams?

Trust boundaries render as structural frames with distinct SVG metadata attributes such as data-composition-frame-kind="security-group". These visual containers are defined in the architecture JSON and provide immediate visual indication of security zones within the system topology.

Does Archify support deterministic builds for audit compliance?

Yes, the scripts/build-zip.sh script produces deterministic ZIP archives with recorded hashes that are verified against release metadata before publishing. This ensures that every distributed artifact is bit-for-bit reproducible from the source code, meeting compliance requirements for supply chain verification.

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