# How Evidence-Backed Source References Enable Git-Verified File Opening in Archify

> Discover how Archify uses structured src objects with commit SHAs and file paths for Git-verified file opening. Access exact repository locations via clickable SRC badges.

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

---

**Archify enables Git-verified file opening by embedding a structured `src` object—containing a commit SHA, file path, and optional line range—into evidence-backed nodes, then rendering this as a clickable `SRC n` badge that constructs a permalink to the exact repository location.**

Archify is an open-source architecture diagramming tool where **evidence-backed nodes** carry cryptographic provenance. According to the `tt-a1i/archify` source code, these nodes store immutable references to specific Git commits, allowing users to open the exact source files that generated the diagram content. This mechanism ensures that every architectural claim in the diagram remains traceable to a verifiable, public Git object.

## The Anatomy of Evidence-Backed Source References

Evidence-backed nodes in Archify contain a hidden **source reference** property named `src` that pins the node to a specific state of the repository. This reference is stored in the node's JSON representation and contains three critical fields:

- **`src.commit`** – The full SHA-1 hash of the public commit that generated the snapshot.
- **`src.path`** – The repository-relative path to the source file contributing the fact.
- **`src.startLine` and `src.endLine`** (optional) – The specific line range within the file that backs the diagram element.

Only nodes carrying this `src` object qualify as evidence-backed. Ordinary nodes lack this property and do not display the Git-verified opening capability.

```json
{
  "id": "node-42",
  "type": "service",
  "label": "Auth Service",
  "src": {
    "commit": "9f1a1cf7e4b2a9d3c4e5f6a7b8c9d0e1f2a3b4c5",
    "path": "src/auth/service.js",
    "startLine": 12,
    "endLine": 27
  }
}

```

## How Archify Constructs Git-Verified URLs

When rendering the diagram, Archify's viewer dynamically constructs a permalink using the `src` data. The system generates a URL following the GitHub blob pattern:

```text
https://github.com/<owner>/<repo>/blob/<commit>/<path>#L<startLine>-L<endLine>

```

For the example above, the generated URL would be:

```text
https://github.com/tt-a1i/archify/blob/9f1a1cf7e4b2a9d3c4e5f6a7b8c9d0e1f2a3b4c5/src/auth/service.js#L12-L27

```

This URL construction ensures that clicking the evidence beacon opens a **Git-verified view** of the exact source location. The viewer never invents or infers a location; it strictly displays what is recorded in the **Semantic Passport** attached to the snapshot.

## Implementation in the HTML Viewer

The visual implementation resides in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html), where the viewer renders a small `SRC n` badge for each evidence-backed node. As documented in [`/DESIGN.md`](https://github.com/tt-a1i/archify/blob/main//DESIGN.md) at lines 205-206, this badge is a "viewer-only `SRC n` capsule" that is deliberately stripped from every canonical visual export to prevent documentation leakage of internal source paths.

The HTML template includes the following structure:

```html
<div class="node" data-id="node-42">
  <span class="label">Auth Service</span>
  <span class="ds-evidence-beacon">SRC 1</span>
</div>
<script>
nodeElement.addEventListener('click', () => {
  const src = nodeData.src;
  const url = `https://github.com/${owner}/${repo}/blob/${src.commit}/${src.path}#L${src.startLine}-L${src.endLine}`;
  window.open(url, '_blank');
});
</script>

```

The `ds-evidence-beacon` class identifies the badge, while the attached event handler builds the complete GitHub URL from the node's `src` properties. This implementation guarantees that the **Git-verified file opening** feature is available only in the interactive viewer, not in static exports.

## Source Documentation References

The evidence-backed source reference system is documented across three key files in the repository:

- **[`/README.md`](https://github.com/tt-a1i/archify/blob/main//README.md)** (lines 191-192) – Explains that "Evidence-backed Architecture nodes mark themselves `SRC n` and open Git-verified files and line ranges pinned to one public commit."
- **[`/DESIGN.md`](https://github.com/tt-a1i/archify/blob/main//DESIGN.md)** (lines 205-206) – Notes that evidence-backed nodes receive a viewer-only `SRC n` beacon and are stripped from canonical visual exports.
- **[`/research-evidence-beacons-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main//research-evidence-beacons-2026-07-23.md)** (lines 18-19) – Provides the design rationale for evidence beacons as quiet, viewer-only markers that preserve provenance without cluttering exports.

These references confirm that the `src` property is the sole mechanism enabling Archify to guarantee diagram node provenance is traceable to a verifiable Git object.

## Summary

- Evidence-backed nodes store a `src` object containing `commit`, `path`, and optional line numbers.
- The viewer renders this as a `SRC n` badge that constructs a permalink to the exact Git commit and line range.
- URLs follow the format `github.com/<owner>/<repo>/blob/<commit>/<path>#L<start>-L<end>`.
- The feature is viewer-only and excluded from exports, as implemented in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) and documented in [`/DESIGN.md`](https://github.com/tt-a1i/archify/blob/main//DESIGN.md).

## Frequently Asked Questions

### What makes a node "evidence-backed" in Archify?

A node becomes evidence-backed when its JSON representation includes a `src` property containing a valid Git commit SHA and file path. According to the source code in [`/README.md`](https://github.com/tt-a1i/archify/blob/main//README.md), this attachment pins the node to a specific public commit, enabling the Git-verified opening functionality that ordinary nodes lack.

### Can evidence-backed source references link to private repositories?

The current implementation in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) constructs standard GitHub blob URLs. While the reference can store any commit hash from any Git repository, the `SRC n` badge will only successfully open files from public repositories or private repositories where the viewer already has authentication access via browser cookies.

### Why does the `SRC n` badge appear only in the viewer and not exports?

As specified in [`/DESIGN.md`](https://github.com/tt-a1i/archify/blob/main//DESIGN.md) at lines 205-206, the evidence beacon is explicitly a "viewer-only" element that gets stripped from canonical visual exports. This design prevents sensitive file paths and internal source code locations from leaking into externally shared documentation artifacts while preserving the provenance chain within the tool itself.

### What happens if the source file moves or the commit is rebased?

The `src.commit` field stores a full SHA-1 hash, which remains valid as long as the commit exists in the remote repository. However, if the file is moved or the commit is garbage-collected after a rebase, the generated GitHub URL will return a 404 error. Archify stores the reference immutably and does not update paths if the repository structure changes.