How to Add Git Source Evidence to Archify Diagrams

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:

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

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:

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

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

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

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

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 — Sample output showing semantic-passport-evidence elements
• archify/SKILL.md — Formal JSON schema for the source object
• 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 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. 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.

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