# How Repository Evidence Works in Architecture Diagrams

> Discover how Archify links architecture diagrams to exact code versions. Verify Git repositories against GitHub URLs and commit SHAs for immutable source code traceability.

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

---

**Archify embeds cryptographically verified source code links into architecture diagrams by validating local Git repositories against declared GitHub URLs and 40-character commit SHAs, ensuring every visual node maps to an immutable, exact line of code.**

Repository evidence transforms static architecture diagrams into interactive, source-verified documentation within the Archify ecosystem. By pinning visual components to specific Git commits and file paths, the system creates an unbreakable chain between high-level design and implementation details. This feature operates entirely within the `architecture` diagram type and requires explicit opt-in through JSON metadata and CLI flags according to the `tt-a1i/archify` source code.

## Declaring Repository Evidence in Diagram JSON

To enable verification, the diagram must declare repository metadata at the top level and attach source references to individual components.

### The meta.repository Object

The diagram JSON requires a `meta.repository` object containing a public GitHub URL and a full 40-character commit SHA. This declaration signals Archify to activate the verification pipeline defined in `archify/renderers/shared/repository-evidence.mjs`.

```json
{
  "type": "architecture",
  "meta": {
    "repository": {
      "url": "https://github.com/example/project",
      "revision": "9f1a1cf1afdc04d7b5406782b40dfec76d9bc798"
    }
  }
}

```

### Component Source Entries

Individual components list their evidence in a `sources` array. Each entry specifies a relative file path and optional line range. The `verifiedSourcePath` function validates these entries for POSIX compliance and path safety.

```json
{
  "components": [
    {
      "id": "router",
      "label": "API Router",
      "sources": [
        {
          "path": "src/router.js",
          "line": 42,
          "end_line": 58,
          "label": "Router entry point"
        }
      ]
    }
  ]
}

```

## The Repository Evidence Verification Pipeline

When the user invokes the renderer with `--repo-root`, Archify executes a multi-stage validation pipeline to ensure the local repository state matches the authored metadata exactly.

### Architecture-Only Restriction

Repository evidence is strictly limited to diagrams of type `architecture`. The `hasRepositoryEvidence` function checks the diagram type at lines 81-86 of `repository-evidence.mjs` and aborts with a diagnostic error if evidence is present in any other diagram type.

### CLI Flag and Local Repository Binding

The `--repo-root <path>` flag is mandatory when repository evidence is declared. The `verifyRepositoryEvidence` function (lines 114-119) uses this path to locate the local checkout that corresponds to the authored repository metadata.

```bash
archify render diagram.json --repo-root /path/to/project --mode architecture

```

### Git Remote and Revision Verification

Using internal helpers `runGit` and `gitValue` (lines 20-38), Archify performs three critical validations:

1. Resolves the repository top-level directory
2. Verifies the `origin` remote matches `meta.repository.url`
3. Confirms the declared commit SHA exists in the local Git history

### Source Path Syntax Validation

The `verifiedSourcePath` function (lines 47-64) enforces strict POSIX-style relative path constraints:

- No leading slashes or backslashes
- No empty segments, `.`, `..`, or `.git` components
- Valid line range syntax where `end_line` ≥ `line`

### Blob and Line Count Verification

For each source entry, Archify executes `git cat-file -t` to verify the object is a **blob** (file) rather than a tree or commit. When line numbers are specified, the system runs `git show` to fetch content and validate that the requested line range exists within the file boundaries (lines 86-100).

## Generating Verified Evidence in the Output

Successfully verified sources are transformed into **Semantic Passport** entries. The rendered HTML includes a **source-evidence beacon**—a small clickable icon on the visual node that expands to reveal a verified GitHub URL:

```

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

```

This link points directly to the exact code lines, pinned to the immutable commit SHA declared in the diagram metadata.

## Error Handling and Diagnostic Guidance

When any verification check fails, the `evidenceFailure` function (lines 9-18) throws structured diagnostic errors containing:

- A machine-readable `code` for automated processing
- A human-readable `message` explaining the failure
- A list of `supportedFixes` (e.g., "install Git", "use a repository-relative path", "pin a full commit SHA")

This structured error format guides diagram authors to correct metadata issues before the final HTML artifact is generated, preventing broken or unverified links from appearing in published documentation.

## Summary

- Repository evidence requires the `architecture` diagram type and explicit `--repo-root` CLI flag to activate the verification pipeline.
- The `meta.repository` object must contain a valid GitHub URL and full 40-character commit SHA.
- Local Git validation occurs through `runGit` and `gitValue` helpers, verifying remotes, revisions, and object types before rendering.
- Source paths undergo strict POSIX validation via `verifiedSourcePath` to prevent directory traversal and ensure cross-platform compatibility.
- Verified evidence renders as clickable **source-evidence beacons** linking to immutable GitHub blob URLs with line anchors.
- All failures route through `evidenceFailure`, providing structured diagnostics with `supportedFixes` for rapid remediation.

## Frequently Asked Questions

### Can I use repository evidence with sequence or flow diagrams?

No, repository evidence is restricted to `architecture` type diagrams only. The `hasRepositoryEvidence` function in `archify/renderers/shared/repository-evidence.mjs` explicitly checks the diagram type and aborts if evidence is present in other formats, maintaining a strict separation between architectural views and behavioral diagrams.

### What happens if my local repository is on a different commit than declared?

Archify validates the commit SHA against the local Git history using `gitValue` commands. If the revision is missing or the `origin` remote URL mismatches the `meta.repository.url`, `evidenceFailure` emits a diagnostic error suggesting you fetch the remote, checkout the correct commit, or correct the repository path in your diagram JSON.

### Are absolute paths or parent directory references allowed in source entries?

No, the `verifiedSourcePath` function explicitly rejects paths containing leading slashes, backslashes, `.`, or `..` segments to prevent directory traversal attacks. All source paths must be relative POSIX paths without empty segments or `.git` components, ensuring the diagram remains portable and secure.

### Is the --repo-root flag optional when repository metadata is present?

No, the `--repo-root` flag is mandatory when repository evidence is declared. Without it, `verifyRepositoryEvidence` cannot locate the local checkout to perform Git validation, and the renderer will abort with a diagnostic error before generating any HTML output.