# How to Add Git Source Evidence to Archify Diagrams

> Learn to add Git source evidence to Archify diagrams. Attach verifiable source to diagram nodes using a source block and the --repo-root flag for enhanced traceability.

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

---

**Archify attaches verifiable Git source evidence to diagram nodes by adding a `source` block to the JSON IR and rendering with the `--repo-root` flag.**

This guide shows you how to link any architecture diagram element directly to the exact lines of code that implement it. By the end, you'll produce diagrams where users can click a node and jump straight to the relevant file, commit, and line range on GitHub.

## What Is Source Evidence in Archify?

**Source evidence** is Archify's mechanism for proving that a diagram element corresponds to real code. Each evidenced node carries a cryptographically verifiable reference to a Git commit, file path, and line range. When rendered, Archify validates this reference against your local repository and injects a clickable badge into the output HTML.

The feature is implemented in `archify/renderers/shared/repository-evidence.mjs`, which enforces the **architectural contract** for evidence validation and receipt generation.

## Step 1: Mark the Node with a Source Block

Add a `source` object to any node in your diagram's JSON IR. This object requires five fields:

| Field | Description |
|-------|-------------|
| `repo` | Full HTTPS URL to the GitHub repository |
| `revision` | Full 40-character commit SHA |
| `path` | Relative path from repo root to the target file |
| `line` | Starting line number (1-indexed) |
| `endLine` | Ending line number (inclusive) |

Here is a complete node definition with source evidence:

```json
{
  "id": "router",
  "label": "CLI router",
  "kind": "service",
  "source": {
    "repo": "https://github.com/mco-org/mco",
    "revision": "9f1a1cf1afdc04d7b5406782b40dfec76d9bc798",
    "path": "runtime/cli.py",
    "line": 1945,
    "endLine": 1945
  }
}

```

The `source` block tells Archify to treat this node as **evidenced**. Without it, the node renders without Git linking.

## Step 2: Enable Git Verification During Rendering

Archify validates source evidence only when you supply a local repository root. Use the `--repo-root` flag to point to your cloned repository:

```bash
node archify/bin/archify.mjs render \
    examples/web-app.json \
    /tmp/web-app.html \
    --repo-root $(pwd) \
    --quality showcase

```

The CLI entry point at `archify/bin/archify.mjs` performs these checks:

1. **Commit existence** — Verifies `revision` exists in the Git object database
2. **Path validity** — Confirms `path` resolves inside the repository
3. **Line range bounds** — Ensures `line` and `endLine` fall within file length

If any check fails, the renderer aborts with:

```

Rendered source evidence receipt is incomplete.

```

This error originates at line 742 of `archify/bin/archify.mjs`. Successful validation produces a receipt JSON and proceeds to HTML generation.

## Step 3: Deliver Verified Diagrams

The `deliver` sub-command automatically runs verification before publishing. This ensures gallery artifacts cannot be updated with unverified evidence:

```bash
node archify/bin/archify.mjs deliver \
    examples/web-app.json \
    docs/gallery/artifacts/web-app.architecture.html \
    --repo-root $(pwd) \
    --open \
    --json

```

The delivery pipeline in `archify.mjs` atomically replaces the previous artifact only after receiving a passing receipt. This prevents race conditions where broken evidence might briefly appear public.

## How Evidence Appears in the Output

Verified nodes receive a clickable **source badge** in the generated HTML. Clicking it opens the constructed GitHub URL:

```

https://github.com/mco-org/mco/blob/9f1a1cf…/runtime/cli.py#L1945

```

The evidence data hides in a `<div class="semantic-passport-evidence">` element, as seen in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html). This element contains the full `source` object and verification receipt, enabling downstream tools to audit evidence without re-cloning repositories.

## Verification Guarantees

| Aspect | Validation Logic | Location |
|--------|----------------|----------|
| Commit SHA exists | `git cat-file -t <sha>` must return `commit` | `repository-evidence.mjs` |
| Path inside repo | Resolved path must start with `--repo-root` | Same module |
| Lines in range | `line` ≥ 1 and `endLine` ≤ total file lines | Same module |
| URL determinism | GitHub URL built from verified fields | [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) |

Failed validation aborts rendering. This design prevents **evidence fabrication** — you cannot claim a node links to code without actually possessing that commit in your local Git data.

## Complete Working Example

**Diagram source** ([`diagram.json`](https://github.com/tt-a1i/archify/blob/main/diagram.json)):

```json
{
  "nodes": [
    {
      "id": "db",
      "label": "Postgres",
      "kind": "database",
      "source": {
        "repo": "https://github.com/tt-a1i/archify",
        "revision": "a73047b27e3b423fc8ab6ebd1ac84fd4ecb2e782",
        "path": "archify/src/storage.js",
        "line": 42,
        "endLine": 48
      }
    }
  ],
  "edges": []
}

```

**Render command**:

```bash
git clone https://github.com/tt-a1i/archify.git
cd archify
node archify/bin/archify.mjs render diagram.json output.html --repo-root . --quality showcase

```

**Deliver command** (for publishing):

```bash
node archify/bin/archify.mjs deliver diagram.html gallery/ --repo-root . --open

```

## Key Source Files

- `archify/renderers/shared/repository-evidence.mjs` — Core verification and receipt logic
- `archify/bin/archify.mjs` — CLI parsing, `--repo-root` handling, error emission at line 742
- [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) — Sample output showing `semantic-passport-evidence` elements
- [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) — Formal JSON schema for the `source` object
- [`docs/research-repo-evidence-passport-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-repo-evidence-passport-2026-07-23.md) — Design rationale for evidence passports

## Summary

- Add a `source` object to any node in your Archify JSON IR to mark it as evidenced
- Include `repo`, `revision`, `path`, `line`, and `endLine` in the source block
- Pass `--repo-root <path>` when rendering to enable Git verification
- Use `deliver` instead of `render` to guarantee verified artifacts in production
- Failed verification aborts with "Rendered source evidence receipt is incomplete" from `archify.mjs` line 742
- Output HTML contains clickable badges linking to exact GitHub lines

## Frequently Asked Questions

### What happens if the commit SHA is shortened?

Archify requires the full 40-character SHA in `source.revision`. Shortened SHAs fail validation because `repository-evidence.mjs` performs exact string matching against the Git object database. Always use `git rev-parse HEAD` to obtain the full SHA.

### Can I evidence multiple files for one node?

No. The `source` object supports a single `path` with one line range. For nodes backed by multiple files, Archify recommends either splitting the concept into multiple evidenced nodes or selecting the single most representative file range. The JSON schema in [`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/SKILL.md) explicitly defines `source` as a singular object, not an array.

### Does Archify support GitLab or other hosts?

The current implementation generates GitHub URLs in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html). For GitLab or self-hosted Git, fork `repository-evidence.mjs` and modify the URL construction logic. The verification layer (`--repo-root` checks) is host-agnostic since it only inspects local Git data.

### How do I update evidence when code changes?

Edit the `revision` field to point to the new commit SHA, update `line`/`endLine` if the code moved, and re-render with `--repo-root`. The `deliver` command ensures you cannot accidentally publish stale evidence — verification fails if the old SHA no longer exists in your updated local clone.