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

> Add source evidence verification to your Archify architecture diagrams. Link visual elements to JSON manifests and display automatic verification badges.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/evidence.json)
- **Renderer Hooks**: Validation and UI injection logic in the rendering pipeline ([`archify/renderers/sequence/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/sequence/README.md), [`archify/renderers/lifecycle/README.md`](https://github.com/tt-a1i/archify/blob/main/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:

```mermaid
%%{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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/evidence.json). Create a file at `evidence/<source-id>.json` relative to your diagram:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md):

```markdown

## 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`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/lifecycle/README.md).

## Rendering with Verification Enabled

Execute rendering with evidence validation active:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/evidence.json)
- **Renderer hooks** in [`archify/renderers/sequence/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/sequence/README.md) and [`archify/renderers/lifecycle/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/lifecycle/README.md) execute validation and badge injection
- **Delivery contracts** ([`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/evidence.json). YAML is supported experimentally in versions after the schema stabilization documented in [`docs/research-evidence-beacons-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/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.