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

> Learn to integrate repository evidence with Git in Archify. This guide shows how Archify embeds immutable Git evidence in HTML for one-click navigation to exact commits and line ranges.

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

---

**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:

```bash

# 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`:

```javascript
// 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/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`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) demonstrates the pattern:

```javascript
// 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:

```html
<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`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) | HTML template with injection point | 7149-7151 |
| [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) | Reference viewer implementation | 7215-7223 |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/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:

```bash

# 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.