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

> Learn to create source evidence links to Git repositories in Archify architecture diagrams. Attach verifiable files and line ranges to nodes for direct access.

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

---

**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)](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)](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)](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md#L94) specifies the exact schema fields required.

### Required JSON Structure

```json
{
  "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

```bash

# 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)](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:
   ```bash
   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:
   ```bash
   node archify/bin/archify.mjs validate architecture my-diagram.json \
     --repo-root . \
     --quality showcase
   ```

4. **Generate the deliverable** HTML with embedded evidence links:
   ```bash
   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)](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)](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.