How to Create Source Evidence Links to Git Repositories in Archify Architecture Diagrams

Archify enables architects to attach verifiable source evidence to diagram nodes, allowing viewers to click through directly to specific files and line ranges in Git repositories via a SRC n badge interface.

Archify, an open-source architecture diagramming tool from the tt-a1i/archify repository, implements a rigorous source-evidence system that links visual components to their implementation in version control. By declaring repository metadata and source locations in your diagram JSON, you create an auditable trail from high-level architecture down to exact commit SHAs and file ranges. This feature ensures that stakeholders can verify design decisions against actual code without cluttering exported visual assets.

Understanding Source Evidence in Archify

Source evidence in Archify represents an opt-in contractual link between a diagram node and its originating source code. According to [archify/SKILL.md](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md#L191), this feature activates only when explicitly requested through the diagram's configuration schema.

The system performs three critical validations before embedding evidence:

1. Repository URL verification – Confirms the local checkout's remote origin matches the declared URL
2. Commit SHA pinning – Ensures the evidence points to an immutable commit rather than a floating branch
3. Blob existence checking – Validates that specified file paths and line ranges exist at that commit

As documented in [archify/schemas/README.md](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md#L129), this verification prevents broken links and guarantees that the evidence remains accurate across diagram versions.

Configuring Repository Evidence in Diagram JSON

To enable source evidence, you must add a repository block to your architecture diagram JSON. The [archify/references/authoring-contract.md](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md#L94) specifies the exact schema fields required.

Required JSON Structure

{
  "type": "architecture",
  "meta": { "quality_profile": "showcase" },
  "nodes": [
    {
      "id": "api",
      "label": "API Server",
      "kind": "backend",
      "evidence": true
    }
  ],
  "repository": {
    "url": "https://github.com/tt-a1i/archify",
    "commit": "a73047b27e3b423fc8ab6ebd1ac84fd4ecb2e782",
    "sources": [
      { "path": "archify/SKILL.md", "range": "191-200" },
      { "path": "archify/core/validator.mjs" }
    ]
  }
}

Key fields:

• url: The canonical HTTPS URL of the Git repository
• commit: The full 40-character SHA of the commit to pin against
• sources: Array of objects containing path (relative to repo root) and optional range (line numbers in start-end format)

You may specify up to three source locations per diagram, allowing you to reference multiple files that justify a particular architectural decision.

CLI Verification with --repo-root

Archify requires local verification before embedding evidence links. When running archify render, archify validate, archify preview, or archify deliver, you must pass the --repo-root flag pointing to your local checkout.

Verification Commands

# Render with evidence verification

node archify/bin/archify.mjs render architecture diagram.json \
  --repo-root /path/to/local/archify \
  --output diagram.html

# Validate evidence links without generating output

node archify/bin/archify.mjs validate architecture diagram.json \
  --quality showcase \
  --repo-root /path/to/local/archify \
  --json

# Deliver final artifact with embedded evidence

node archify/bin/archify.mjs deliver architecture diagram.json output.html \
  --quality showcase \
  --repo-root /path/to/local/archify \
  --json

The CLI performs a strict verification routine:

• Checks that .git/config contains the matching remote URL
• Validates the commit SHA exists in the repository
• Confirms each source path exists at that commit
• Verifies line ranges are within valid bounds

If verification fails, the CLI emits an evidence-related diagnostic indicating whether the error stems from URL mismatch, missing commits, or invalid line ranges.

How the SRC Badge Renders in the Viewer

Once verified and rendered, evidence-enabled nodes display a small SRC n badge in the upper-right corner within the HTML viewer only. As detailed 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#L18), this beacon is viewer-only and automatically strips from all canonical exports (SVG, PNG, WebM).

When a user clicks the badge, the Semantic Passport panel opens, displaying deep links formatted as:

https://github.com/owner/repo/blob/<SHA>/path/to/file#L10-L20

This behavior ensures that exported diagrams remain self-contained visual artifacts while the interactive HTML viewer maintains full traceability to source code.

Complete Workflow Example

Follow this end-to-end workflow to implement source evidence in your architecture diagrams:

1. Prepare your diagram JSON with the repository block and enable evidence on specific nodes by setting "evidence": true.

2. Verify your local repository matches the declared commit:

   cd /path/to/repo
   git log --oneline -1
   # Ensure this matches the commit SHA in your JSON
   

3. Run validation to catch evidence errors early:

   node archify/bin/archify.mjs validate architecture my-diagram.json \
     --repo-root . \
     --quality showcase

4. Generate the deliverable HTML with embedded evidence links:

   node archify/bin/archify.mjs deliver architecture my-diagram.json \
     final-output.html \
     --repo-root . \
     --quality showcase

5. Distribute the HTML viewer to stakeholders, who can now click SRC badges to jump directly to the relevant source files.

Summary

• Source evidence links diagram nodes to specific Git commits and file ranges through an opt-in JSON configuration.
• The repository block requires url, commit, and sources fields to establish verifiable links.
• Always use --repo-root when running Archify CLI commands to enable local verification against your working copy.
• Evidence verification checks remote URLs, commit SHAs, and file existence before embedding links.
• The SRC n badge appears only in the HTML viewer (not exports) and opens the Semantic Passport containing deep links to the repository.
• Reference [archify/SKILL.md](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) and [archify/references/authoring-contract.md](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) for schema details.

Frequently Asked Questions

What happens if the commit SHA in my diagram JSON doesn't match my local repository?

Archify will emit a verification error during the --repo-root check and refuse to embed the evidence. You must either checkout the exact commit declared in your JSON or update the JSON to match your current HEAD commit. This ensures evidence links remain immutable and traceable to specific code states.

Can I link to multiple source files from a single diagram?

Yes. The schema supports up to three source locations in the sources array. Each entry can specify a different file path and optional line range, allowing you to reference multiple implementation files that support a single architectural component.

Why doesn't the SRC badge appear in my exported PNG or SVG files?

The SRC badge is intentionally viewer-only according to the evidence beacon specification. It appears exclusively in the HTML viewer output to maintain clean, self-contained visual exports while preserving interactive traceability in the web-based deliverable.

Do I need to use --repo-root for every Archify command?

You must use --repo-root for any command that processes or validates evidence: render, validate, preview, and deliver. Omitting this flag disables evidence verification, causing Archify to skip the source link embedding even if your JSON contains a repository configuration.

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