How to Integrate Repository Evidence with Git in Archify: A Complete Guide

Archify attaches immutable Git evidence to diagram nodes through a sourceEvidenceJson payload embedded in generated HTML, enabling one-click navigation to exact file commits and line ranges.

Integrating repository evidence with Git in Archify transforms static architecture diagrams into verifiable, interactive documents. When you generate a diagram with source evidence enabled, Archify records the repository URL, commit SHA, and precise source locations—then renders clickable beacons that open the exact Git blame view. This article walks through the complete implementation based on the tt-a1i/archify source code.

What Is Source Evidence in Archify?

Source evidence is a cryptographic receipt of provenance that links diagram nodes to their originating code. According to the Archify README, only nodes explicitly marked as needing proof receive this treatment: "Source evidence, only when requested – evidence‑backed Architecture nodes mark themselves SRC n and open Git‑verified files and line ranges pinned to one public commit; ordinary artifacts stay source‑free"【https://github.com/tt-a1i/archify/blob/main/README.md#L191-L194】.

This design keeps diagrams clean while providing audit-grade traceability for critical components.

Generating Source Evidence with the CLI

The Archify CLI produces source evidence when you use the --quality showcase flag. This triggers the proof-generation pipeline that embeds verified Git references into the output.

Run the following command to generate a diagram with repository evidence:

# Generate a runtime architecture diagram with verified evidence

node archify/bin/archify.mjs guide "Map the runtime of a repo" \
    --quality showcase --json > diagram.html

The --json flag ensures the output includes the sourceEvidenceJson block, which the renderer later embeds into HTML【https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs#L741-L749】.

How Archify Embeds Evidence in HTML

Archify uses a three-stage pipeline to integrate repository evidence with Git into viewable diagrams.

Stage 1: Creating the JSON Payload

The renderer builds a structured evidence object containing:

• repository.url — the Git remote URL
• repository.revision — the immutable commit SHA
• nodes — map of node IDs to source locations (path, line, label, href)

This payload is serialized as JSON and prepared for embedding.

Stage 2: Injecting the Script Tag

In archify/renderers/shared/utils.mjs, the renderer inserts the evidence as a <script> element with ID archify-source-evidence-data:

// From archify/renderers/shared/utils.mjs lines 159-166
const evidenceScript = `<script id="archify-source-evidence-data" type="application/json">
${JSON.stringify(sourceEvidenceJson, null, 2)}
</script>`;

This script tag is placed immediately before the closing </body> tag in archify/assets/template.html【https://github.com/tt-a1i/archify/blob/main/archify/renderers/shared/utils.mjs#L159-L166】【https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html#L7149-L7151】.

Stage 3: Parsing and Rendering Beacons

The viewer code reads this embedded JSON and renders interactive beacons. The implementation in examples/web-app.html demonstrates the pattern:

// Adapted from examples/web-app.html lines 7215-7223
const evidenceEl = document.getElementById('archify-source-evidence-data');
if (evidenceEl) {
  const data = JSON.parse(evidenceEl.textContent);
  Object.entries(data.nodes).forEach(([nodeId, refs]) => {
    const nodeEl = document.querySelector(`[data-node-id="${nodeId}"]`);
    if (nodeEl) {
      const beacon = document.createElement('div');
      beacon.className = 'source-evidence-beacon';
      beacon.title = 'Open verified source';
      beacon.onclick = () => window.open(refs[0].href, '_blank');
      nodeEl.appendChild(beacon);
    }
  });
}

Clicking a beacon opens the Git URL in a new tab, jumping directly to the pinned commit and line number.

Anatomy of the Evidence Payload

Here is the complete structure of the embedded JSON:

<script id="archify-source-evidence-data" type="application/json">
{
  "schemaVersion": 1,
  "verified": true,
  "repository": {
    "url": "https://github.com/your-org/your-repo",
    "revision": "a1b2c3d4e5f6789abcdef0123456789abcdef0123"
  },
  "referenceCount": 3,
  "nodes": {
    "api": [{
      "path": "src/api.js",
      "line": 42,
      "label": "API entry",
      "href": "https://github.com/your-org/your-repo/blob/a1b2c3d/src/api.js#L42"
    }],
    "db": [{
      "path": "src/db.js",
      "line": 10,
      "label": "DB client",
      "href": "https://github.com/your-org/your-repo/blob/a1b2c3d/src/db.js#L10"
    }]
  }
}
</script>

The href field uses GitHub's permalink format: https://github.com/{owner}/{repo}/blob/{revision}/{path}#L{line}. This format ensures the link remains valid even if the file changes in future commits.

Verification Guarantees

Archify's validation step checks that the recorded commit SHA matches the repository snapshot used to build the diagram. This immutable binding prevents evidence tampering after generation—you cannot retroactively change a diagram to point to different code without regenerating from the actual source.

The automated test suite in archify/test/repository-evidence.test.mjs verifies that the evidence script appears only when expected and contains valid structured data【https://github.com/tt-a1i/archify/blob/main/archify/test/repository-evidence.test.mjs#L53-L110】.

Key Configuration Files

File	Purpose	Critical Lines
archify/bin/archify.mjs	CLI entry point, produces JSON payload	741-749
archify/renderers/shared/utils.mjs	Embeds archify-source-evidence-data script	159-166
archify/assets/template.html	HTML template with injection point	7149-7151
examples/web-app.html	Reference viewer implementation	7215-7223
archify/SKILL.md	Formal schema for evidence payload	Full document
archify/test/repository-evidence.test.mjs	Automated verification tests	53-110

Complete Working Example

Generate and inspect evidence in one workflow:

# 1. Create diagram with evidence

node archify/bin/archify.mjs guide "Show API request flow" \
    --quality showcase --json > api-flow.html

# 2. Verify evidence was embedded

grep -A5 "archify-source-evidence-data" api-flow.html

# 3. Open in browser to test clickable beacons

open api-flow.html

In the browser, nodes with source evidence display a "Verified source" badge. Hover to preview, click to open Git【https://github.com/tt-a1i/archify/blob/main/docs/cases/mco-runtime.architecture.html#L4845-L4856】.

Summary

• Use --quality showcase to enable source evidence generation in the Archify CLI
• Evidence is opt-in — only nodes marked SRC n receive Git links, keeping diagrams uncluttered
• Immutable commits — the revision SHA pins evidence to an unchangeable repository state
• Three-layer pipeline — CLI generates JSON, renderer embeds script, viewer renders beacons
• Verified provenance — cryptographic binding between diagram and source prevents tampering

Frequently Asked Questions

What does the --quality showcase flag actually do?

The --quality showcase flag activates Archify's proof-generation pipeline. According to the source code in archify/bin/archify.mjs, this triggers the full evidence collection process that analyzes the repository, records commit SHAs, and builds the sourceEvidenceJson payload for qualifying nodes【https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs#L741-L749】. Without this flag, diagrams generate without embedded source evidence.

Can I use repository evidence with private Git repositories?

Yes. The sourceEvidenceJson structure stores the repository URL and commit SHA regardless of visibility. For private repositories, the generated href links will use your private Git host's URL format (e.g., https://git.company.com/...). Viewers will need appropriate repository access for the links to resolve successfully.

How does Archify prevent evidence from becoming stale?

Archify binds evidence to immutable commit SHAs rather than branch names. The revision field contains the full 40-character SHA, creating a permanent permalink to that exact repository state. Even if the file moves or changes in later commits, the evidence link remains valid for the historical snapshot. Regenerating the diagram from the current HEAD creates fresh evidence for the latest code.

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