How to Add Source Evidence Verification to Your Architecture Diagram in Archify

Embed verifiable source references directly into your diagrams using Archify's evidence beacon system, which links visual elements to JSON manifests and renders verification badges automatically.

Archify enables source evidence verification for architecture diagrams through a declarative beacon system. Each diagram element can reference an external evidence manifest containing provenance metadata—author, timestamp, URL, cryptographic hash—that the renderer validates and displays as a verification badge. This article explains how to implement this workflow using the actual source files from tt-a1i/archify.

How Source Evidence Verification Works in Archify

The verification pipeline in Archify operates through three coordinated components as implemented in the repository:

• Evidence Beacons: Inline declarations in diagram source files that annotate elements with source identifiers
• Evidence Manifests: JSON/YAML files storing structured provenance metadata per the schema in archify/schemas/evidence.json
• Renderer Hooks: Validation and UI injection logic in the rendering pipeline (archify/renderers/sequence/README.md, archify/renderers/lifecycle/README.md)

When you run archify render, the lifecycle renderer first validates all evidence references against their manifests. Valid references trigger badge injection; invalid or missing references generate warnings or build failures based on your configuration.

Adding an Evidence Beacon to Your Diagram

Evidence beacons use Mermaid comment syntax to declare source identifiers without disrupting diagram parsing.

Place the beacon immediately before the target element:

%%{evidence: "api-v1-design"}%%
graph LR
    A[Client] --> B[API Gateway]
    
%%{evidence: "service-auth-spec"}%%
    B --> C[Auth Service]

The beacon syntax %%{evidence: "<source-id>"}%% is parsed by the sequence renderer at archify/renderers/sequence/README.md. Each beacon scopes to the subsequent diagram element until the next beacon or diagram end.

Creating and Validating Evidence Manifests

Evidence manifests must conform to archify/schemas/evidence.json. Create a file at evidence/<source-id>.json relative to your diagram:

{
  "type": "design-doc",
  "author": "alice@example.com",
  "url": "https://github.com/tt-a1i/archify/blob/main/docs/api-v1-design.md",
  "hash": "sha256:3f2e1c9d8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0",
  "timestamp": "2026-07-15T12:00:00Z"
}

Required fields per the schema:

• type: Categorization of the evidence source (e.g., design-doc, rfc, change-set)
• author: Responsible party email or identifier
• url: Canonical location of the source document
• hash: Cryptographic fingerprint of the referenced artifact for integrity verification
• timestamp: ISO 8601 datetime of manifest creation or source publication

The lifecycle renderer validates manifests against this schema before rendering. Hash mismatches trigger validation failures.

Configuring External Evidence Stores

For centralized evidence management, register external stores in archify/references/delivery-contract.md:

## Evidence Store References

- name: corporate-evidence-repo
  url: https://github.com/org/evidence-store
  path: /manifests/architecture/
  format: json

This configuration directs the renderer to resolve %%{evidence: "corporate-evidence-repo:api-v1-design"}%% by fetching from the specified remote path. The delivery contract is processed during renderer initialization in archify/renderers/lifecycle/README.md.

Rendering with Verification Enabled

Execute rendering with evidence validation active:

archify render diagram.mmd --evidence-strict

The --evidence-strict flag converts warnings to errors, failing the build on any unresolved or invalid evidence reference. Without this flag, missing evidence renders with an "unverified" badge.

Rendered output displays a verification badge on annotated elements. Hover interaction reveals the full manifest details: author, timestamp, URL, and hash truncation.

Handling Verification Errors

The renderer emits structured diagnostics for evidence failures:

Error Code	Cause	Resolution
EVIDENCE_MISSING	Beacon references non-existent manifest	Create evidence/<source-id>.json
EVIDENCE_SCHEMA_INVALID	Manifest fails JSON schema validation	Correct fields per archify/schemas/evidence.json
EVIDENCE_HASH_MISMATCH	Artifact content differs from recorded hash	Update hash or investigate source tampering
EVIDENCE_STORE_UNREACHABLE	External evidence store connection failed	Verify network and delivery-contract.md configuration

These errors surface during the lifecycle pre-render phase, enabling early detection of documentation drift.

Advanced: Custom Evidence Types

Extend the base schema by creating evidence/schemas/custom.json and referencing it via $ref in your manifests. Register custom validators in the renderer configuration per patterns documented in docs/research-evidence-beacons-2026-07-23.md.

Summary

• Evidence beacons (%%{evidence: "id"}%%) declare source references inline in Mermaid diagrams
• Evidence manifests store structured provenance in evidence/<id>.json files validated against archify/schemas/evidence.json
• Renderer hooks in archify/renderers/sequence/README.md and archify/renderers/lifecycle/README.md execute validation and badge injection
• Delivery contracts (archify/references/delivery-contract.md) enable centralized evidence store integration
• Strict mode (--evidence-strict) enforces verification integrity in CI/CD pipelines

Frequently Asked Questions

What file format must evidence manifests use?

Evidence manifests must be valid JSON conforming to archify/schemas/evidence.json. YAML is supported experimentally in versions after the schema stabilization documented in docs/research-evidence-beacons-2026-07-23.md.

Can I reference the same evidence source from multiple diagrams?

Yes. Use identical beacon identifiers (%%{evidence: "shared-source"}%%) across diagrams and maintain a single manifest file. The renderer caches manifest lookups within a single render invocation for performance.

How do I disable verification for a specific diagram element?

Omit the evidence beacon for that element. Unannotated elements render without verification badges. To explicitly mark intentional absence of evidence, use %%{evidence: null}%% as documented in the sequence renderer specification.

Does Archify verify the hash against the actual URL content?

By default, the renderer validates hash format and schema compliance only. Remote content hash verification requires enabling the --evidence-fetch-remote flag, which downloads referenced artifacts and computes comparison hashes—significantly slower but cryptographically complete.

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