# How to Add Source Evidence Links to Archify Architecture Nodes Using Git-Verified Files

> Learn how to add Git-verified source evidence links to Archify architecture nodes. Declare repo metadata, add sources to components, and use --repo-root for automatic verification.

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

---

**Annotate Archify architecture nodes with Git-verified source links by declaring repository metadata in your diagram's `meta` section, adding `sources` arrays to components, and rendering with `--repo-root` for automatic verification.**

Archify supports **source-evidence linking**—a feature that pins architecture nodes to exact files and line ranges in a public GitHub repository. This process validates every reference against a local checkout before rendering, ensuring immutable, trustworthy documentation. Below is the complete workflow for adding Git-verified source evidence links to your Archify diagrams.

## Prerequisites for Source-Evidence Linking

Before you begin, you need:

- A **public GitHub repository** URL
- A **full 40-character commit SHA** to pin evidence immutably
- A **local clone** of that repository on the machine running Archify

The verification logic in `archify/renderers/shared/repository-evidence.mjs` enforces these requirements strictly—short SHAs or unverified remotes will fail.

## Step 1: Declare Repository Metadata in the Diagram

Every diagram supporting source evidence must include a `meta.repository` object. This tells Archify where to build GitHub permalinks and which commit to pin.

```json
{
  "meta": {
    "title": "My Service Architecture",
    "repository": {
      "url": "https://github.com/tt-a1i/archify",
      "revision": "2a9c3f5c0e8bdfd4e7b4e2b1a5f6c4c7d9f8e1e2"
    }
  },
  "components": []
}

```

As implemented in `archify/renderers/shared/repository-evidence.mjs` lines 94-100, the `revision` must be a complete SHA—no tags or abbreviated hashes. This guarantees **immutable evidence**: the link will always point to exactly that commit, even if the branch moves forward.

## Step 2: Add Sources Arrays to Components

Within any component definition, include a `sources` array. Each entry specifies a **repo-relative POSIX path**, optional line numbers, and a human-readable label.

```json
{
  "id": "api-gateway",
  "type": "service",
  "label": "API Gateway",
  "sources": [
    {
      "path": "src/gateway/main.py",
      "line": 45,
      "end_line": 89,
      "label": "Request routing logic"
    },
    {
      "path": "src/gateway/config.yaml",
      "label": "Configuration schema"
    }
  ]
}

```

The `sourceHref` function (lines 68-73 in `repository-evidence.mjs`) transforms these entries into GitHub permalinks. Use `line` for single-line references; add `end_line` for ranges. Omit both for file-level links.

## Step 3: Validate Path Syntax

The `verifiedSourcePath` validator (lines 47-65 in `repository-evidence.mjs`) enforces strict path rules:

- **Repo-relative only**: Paths must not start with `/` or include absolute prefixes
- **POSIX format**: Forward slashes (`/`); backslashes are rejected
- **No traversal**: `..` and `.git` segments are blocked to prevent repository escape
- **No null bytes** or other dangerous characters

Invalid paths trigger immediate validation errors with diagnostic messages before Git verification even begins.

## Step 4: Render with `--repo-root` for Verification

Execute Archify with the `--repo-root` flag pointing to your local clone:

```bash
node archify/bin/archify.mjs render architecture diagram.json \
  --out diagram.html \
  --repo-root /home/user/projects/archify

```

The CLI entry point (`archify/bin/archify.mjs`) invokes `verifyRepositoryEvidence` before rendering proceeds. Verification happens in three stages as implemented in lines 87-119 of `repository-evidence.mjs`:

1. **Git-origin check**: Confirms the local clone's remote matches `meta.repository.url` (see `getRepositoryRemotes`, lines 40-47)
2. **SHA existence**: Runs `git cat-file -e` to verify the commit exists
3. **File validation**: Executes `git cat-file -t` to confirm each path points to a blob (file), not a tree or missing object

Optional line-range sanity checks ensure `line` ≤ `end_line` when both are present.

## Step 5: Evidence Embedding and UI Rendering

Upon successful verification, two embedding steps occur:

**Server-side injection**: The `applyTemplate` function in `archify/renderers/shared/utils.mjs` (lines 115-122) injects a `<script id="archify-source-evidence-data">` block containing the verified JSON payload.

**Client-side beacons**: The HTML template ([`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html), line 6816) initializes `Archify.sourceEvidence.installBeacons()`, which reads the payload and renders clickable indicators on each node. Clicking a beacon opens the GitHub file at the exact line range.

## Complete Working Example

Save this as [`api-service.json`](https://github.com/tt-a1i/archify/blob/main/api-service.json):

```json
{
  "meta": {
    "title": "API Service with Evidence",
    "repository": {
      "url": "https://github.com/tt-a1i/archify",
      "revision": "2a9c3f5c0e8bdfd4e7b4e2b1a5f6c4c7d9f8e1e2"
    }
  },
  "components": [
    {
      "id": "cli",
      "type": "process",
      "label": "CLI Tool",
      "sources": [
        {
          "path": "archify/bin/archify.mjs",
          "line": 15,
          "label": "Entry point"
        }
      ]
    },
    {
      "id": "verifier",
      "type": "process",
      "label": "Evidence Verifier",
      "sources": [
        {
          "path": "archify/renderers/shared/repository-evidence.mjs",
          "line": 94,
          "end_line": 112,
          "label": "Core verification logic"
        }
      ]
    },
    {
      "id": "template-utils",
      "type": "service",
      "label": "Template Utilities",
      "sources": [
        {
          "path": "archify/renderers/shared/utils.mjs",
          "line": 115,
          "end_line": 122,
          "label": "Evidence injection"
        }
      ]
    }
  ],
  "edges": [
    { "from": "cli", "to": "verifier", "label": "triggers" },
    { "from": "verifier", "to": "template-utils", "label": "populates" }
  ]
}

```

Render and verify:

```bash
git clone https://github.com/tt-a1i/archify.git
cd archify
git checkout 2a9c3f5c0e8bdfd4e7b4e2b1a5f6c4c7d9f8e1e2

node archify/bin/archify.mjs render architecture api-service.json \
  --out api-service.html \
  --repo-root .

```

The output [`api-service.html`](https://github.com/tt-a1i/archify/blob/main/api-service.html) displays clickable source-evidence beacons on all three nodes. The "Evidence Verifier" node links directly to the verification implementation—meta-documentation that verifies itself.

## Error Handling and Diagnostics

If verification fails, Archify aborts rendering and emits structured errors. The `evidenceFailure` helper (lines 9-17 in `repository-evidence.mjs`) includes a **supportedFixes** array suggesting corrective actions:

- Remote mismatch → Check `meta.repository.url` against `git remote -v`
- Missing commit → Verify SHA exists with `git cat-file -e <sha>`
- Missing file → Confirm path is repo-relative and committed
- Invalid line range → Ensure `line` ≤ `end_line` and both are positive integers

## Key Implementation Files

| File | Purpose |
|------|---------|
| `archify/renderers/shared/repository-evidence.mjs` | Core verification: `hasRepositoryEvidence`, `verifyRepositoryEvidence`, `sourceHref`, `verifiedSourcePath` |
| `archify/renderers/shared/utils.mjs` | HTML injection via `applyTemplate` (lines 115-122) |
| [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) | Client-side beacon rendering (line 6816) |
| `archify/bin/archify.mjs` | CLI orchestration and verification trigger |

## Summary

- **Declare `meta.repository`** with full GitHub URL and 40-character SHA
- **Attach `sources` arrays** to components with POSIX paths and optional line ranges
- **Render with `--repo-root`** pointing to a verified local clone
- **Automatic verification** checks remotes, commits, files, and line sanity via `repository-evidence.mjs`
- **Embedded JSON payload** enables clickable beacons linking to immutable GitHub locations

This workflow guarantees that every architecture node in your Archify diagrams connects to **cryptographically verifiable source code**—no drift, no broken links, no trust assumptions.

## Frequently Asked Questions

### What happens if the commit SHA is not in my local clone?

Archify fails fast with a descriptive error. The `git cat-file -e` check (line 96 in `repository-evidence.mjs`) confirms SHA existence before proceeding. Fetch the missing commit with `git fetch origin <sha>` or use a SHA present in your local repository.

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

No. The `sourceHref` function builds `github.com` permalinks, and verification expects publicly resolvable URLs. Private repository support would require authentication token injection and is not implemented in the current codebase.

### Why does Archify require a local clone instead of using the GitHub API?

Local verification eliminates API rate limits, supports air-gapped environments, and enables `git cat-file` blob type checks without network dependencies. The `--repo-root` approach also validates that you personally have access to the source, adding a trust anchor to the evidence chain.