# How to Add Git-Verified Source Evidence to Archify Diagrams

> Add Git-verified source evidence to Archify diagrams. Include repository, commit, file, and line range in your JSON IR to generate clickable source badges in HTML output.

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

---

**Add a `source` block with repository URL, commit SHA, file path, and line range to any node in your Archify JSON IR, then render with `--repo-root` to generate verified, clickable source badges in the output HTML.**

Archify diagrams can link directly to the exact lines of code that justify each architectural element. This **source evidence** feature binds nodes to specific Git commits, enabling readers to verify claims by clicking through to GitHub. The verification is enforced by the renderer in `archify/renderers/shared/repository-evidence.mjs` and the CLI entry point at `archify/bin/archify.mjs`.

## Mark Nodes with Source Evidence in the JSON IR

Every node in an Archify diagram accepts an optional `source` object that defines the Git-backed evidence. Add this object to nodes you want to prove.

The `source` schema requires:

| Field | Description |
|-------|-------------|
| `repo` | Full HTTPS URL of the GitHub repository |
| `revision` | Exact 40-character commit SHA |
| `path` | File path relative to repository root |
| `line` | Starting line number (1-indexed) |
| `endLine` | Ending line number (inclusive) |

Example node 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
  }
}

```

Archify recognizes this structure through the **architectural contract** defined in `archify/renderers/shared/repository-evidence.mjs`. The presence of a `source` block signals that this node carries verifiable provenance.

## Enable Git Verification During Rendering

Source evidence is validated only when you supply a local repository. Pass `--repo-root <path>` to the `render` or `deliver` commands.

### Render with Verification

```bash

# Clone and enter the referenced repository

git clone https://github.com/tt-a1i/archify.git
cd archify

# Render with repo root for Git verification

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

```

The CLI performs four checks in `archify/renderers/shared/repository-evidence.mjs`:

1. **Commit existence** — The `revision` SHA must exist in the local Git data
2. **File-path sanity** — `path` must resolve to a readable file inside the repo
3. **Line range validity** — `line` and `endLine` must not exceed file length
4. **Link generation** — Constructs deterministic GitHub permalink

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` and prevents unverified or fabricated evidence from reaching the output.

### Deliver with Atomic Replacement

The `deliver` sub-command enforces verification before replacing artifacts:

```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 requires a passing receipt. Only then does the new artifact atomically replace the previous version.

## Consume Evidence in the Generated Viewer

Verified diagrams render **clickable source badges** on evidence-backed nodes. Clicking opens the exact GitHub URL built from the `source` block:

```

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

```

The hidden evidence data is stored in HTML elements with class `semantic-passport-evidence`. These appear throughout the generated output, including [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) in the repository.

## Complete Working Example

This JSON IR defines a database node linked to storage implementation lines:

```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
      }
    }
  ]
}

```

Render and verify:

```bash
node archify/bin/archify.mjs render diagram.json output.html --repo-root . --quality showcase

```

A receipt JSON confirms successful verification. The output HTML contains a verified source badge for the database node.

## Key Implementation Files

| File | Purpose |
|------|---------|
| `archify/renderers/shared/repository-evidence.mjs` | Git verification logic and receipt generation |
| `archify/bin/archify.mjs` | CLI parsing of `--repo-root` and error handling at line 742 |
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Formal `source` schema contract |
| [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) | Example output with `semantic-passport-evidence` elements |
| [`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 the passport concept |

## Summary

- **Add `source` objects** to nodes in your Archify JSON IR with `repo`, `revision`, `path`, `line`, and `endLine`
- **Pass `--repo-root`** when rendering or delivering to enable Git verification against local repository data
- **Verification fails fast** if commits, files, or line ranges are invalid, blocking unproven claims
- **Delivered artifacts** contain clickable source badges that open exact GitHub permalinks

## Frequently Asked Questions

### What happens if the commit SHA in my source block doesn't exist locally?

The renderer aborts with "Rendered source evidence receipt is incomplete." This error from `archify/bin/archify.mjs` line 742 prevents generation of unverified output. Fetch the missing commit into your local repository and retry.

### Can I use source evidence with private GitHub repositories?

Yes. The `repo` URL can point to any accessible Git remote. Viewers clicking source badges need read access to the repository. Archify itself only validates that the commit exists locally; it does not check GitHub permissions during rendering.

### Does Archify support evidence from multiple repositories in one diagram?

Yes. Each node's `source` block specifies its own `repo` URL. You can reference commits from distinct repositories across different nodes. Each `source` block is verified independently against the supplied `--repo-root`, which must contain all referenced histories.