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

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:

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:

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

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

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