# Repository Evidence in Archify: How It Links Diagram Components to Git Source Files

> Discover repository evidence in Archify a verified metadata layer that links diagram components directly to their Git source files for precise traceability.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-04

---

**Repository evidence is an opt-in, revision-pinned metadata layer that Archify attaches to diagram components, creating verified links between visual nodes and their exact locations in Git source files.**

This feature enables precise traceability from architectural diagrams back to the code that implements them. When enabled, every component with a `source` field becomes clickable, opening the exact file and line range in your repository's web interface.

## How Repository Evidence Works

Repository evidence operates as a **verification layer** between your diagram definitions and your Git repository. The system records four critical pieces of metadata for each linked component:

| Metadata | Purpose |
|----------|---------|
| **Repository URL** | Base HTTPS URL (e.g., `https://github.com/owner/repo`) |
| **Revision (commit SHA)** | Exact commit serving as source of truth |
| **File path** | Repository-relative path to the source file |
| **Line range** | One-based start and end line numbers |

### The Verification Pipeline

In `archify/renderers/shared/repository-evidence.mjs`, the `verifyRepositoryEvidence` function performs three validation steps:

1. **Revision existence** — confirms the commit SHA exists in the repository
2. **Blob presence** — verifies the requested file exists at that commit
3. **Line range validity** — checks line numbers against the file's actual line count

Invalid evidence is rejected before reaching the output, preventing broken or misleading source links.

## Generating Diagrams with Repository Evidence

### CLI Usage

Pass `--repo-root` and optionally `--revision` when rendering:

```bash
archify render architecture.json \
  --repo-root https://github.com/example/my-repo \
  --revision $(git rev-parse HEAD) \
  --output diagram.html

```

The CLI entry point in `archify/bin/archify.mjs` parses these flags and forwards them to the rendering pipeline. Without `--repo-root`, evidence generation is skipped entirely.

### Input Schema

Add a `source` object to any node, edge, or group:

```json
{
  "type": "architecture",
  "nodes": [
    {
      "id": "auth-service",
      "label": "Auth Service",
      "source": {
        "path": "src/services/auth.ts",
        "lines": [15, 89]
      }
    }
  ]
}

```

The `lines` array uses **inclusive, one-based indexing** — `[15, 89]` covers lines 15 through 88.

## How Archify Builds Git Source Links

The link construction follows GitHub's standard blob URL scheme:

```

https://github.com/<owner>/<repo>/blob/<revision>/<path>#L<start>-L<end>

```

The `verifyRepositoryEvidence` function generates these URLs during rendering. For the example above, the verified link becomes:

```

https://github.com/example/my-repo/blob/abc123/src/services/auth.ts#L15-L89

```

### The Evidence Payload in Generated HTML

Verified evidence is embedded as JSON inside a `<script>` element with ID `archify-source-evidence-data`. The front-end renderer consumes this payload to create **source-evidence beacons** — visual indicators on diagram nodes with the CSS class `source-evidence-beacon`.

Inspect the payload in browser DevTools:

```js
const data = JSON.parse(
  document.getElementById('archify-source-evidence-data').textContent
);

console.log(data.nodes['auth-service']);
// {
//   href: "https://github.com/example/my-repo/blob/abc123/src/services/auth.ts#L15-L89",
//   label: "Auth Service"
// }

```

The `verified: true` flag confirms the evidence passed all validation checks at render time.

## Opt-In Design and Security

Repository evidence is **disabled by default**. Diagrams rendered without `--repo-root` contain no evidence payload — the test suite explicitly asserts this absence to prevent accidental data leakage.

This design provides two benefits:

- **Privacy** — ordinary diagrams never expose repository structure
- **Integrity** — enabled evidence is cryptographically pinned to a specific commit, preventing stale references  

When verification fails, the renderer omits the offending link rather than emitting a broken reference. The test in `archify/test/repository-evidence.test.mjs` validates this strict behavior.

## Key Implementation Files

| File | Function |
|------|----------|
| `archify/renderers/shared/repository-evidence.mjs` | Contains `hasRepositoryEvidence()` and `verifyRepositoryEvidence()` for link generation and validation |
| `archify/test/repository-evidence.test.mjs` | Test coverage for verification, payload structure, and opt-in/opt-out behavior |
| `archify/bin/archify.mjs` | CLI flag parsing for `--repo-root` and `--revision` |
| [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) | Schema documentation for the repository evidence feature |

## Summary

- **Repository evidence** creates verified, clickable links between diagram components and Git source files
- The feature is **opt-in** via `--repo-root` and pins references to specific commits
- `verifyRepositoryEvidence` validates all metadata before emitting links
- Evidence appears as a JSON payload in the rendered HTML, consumed by front-end beacons
- The default-disabled design protects privacy while enabling precise traceability when needed

## Frequently Asked Questions

### How do I verify that repository evidence was generated correctly?

Inspect the generated HTML for the `<script id="archify-source-evidence-data">` element. Parse its contents to confirm `verified: true` and check that `href` values match your expected GitHub URLs. The test suite uses this same extraction pattern to validate evidence presence.

### What happens if I specify a line range that exceeds the actual file length?

The `verifyRepositoryEvidence` function rejects invalid line ranges during rendering. The evidence for that specific component is omitted, and the diagram still generates but without a source link for the invalid node. Other components with valid evidence remain unaffected.

### Can I use repository evidence with GitLab or other Git hosts?

The current implementation generates GitHub-style blob URLs. For other platforms, you would need to modify `repository-evidence.mjs` to construct platform-specific URL patterns (e.g., GitLab's `/-/blob/` paths). The verification logic remains host-agnostic.

### Why is repository evidence opt-in rather than default?

The opt-in design prevents accidental exposure of repository structure in shared diagrams. It also keeps ordinary diagram files smaller and avoids requiring network access to Git repositories during rendering unless explicitly requested.