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

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.

{
  "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:

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

For the example above, the generated URL would be:

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, where the viewer renders a small SRC n badge for each evidence-backed node. As documented in /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:

<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 (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 (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 (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 and documented in /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, 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 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 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.

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