# How to Connect Archify Architecture Diagrams to a Code Repository (Repository Evidence)

> Connect Archify architecture diagrams to your code repository using Git SHAs and source links. Validate local checkouts and embed evidence directly into your diagrams for a robust workflow.

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

---

**Archify attaches revision-verified repository evidence to architecture diagram nodes by validating your local Git checkout against declared commit SHAs and embedding source links that survive only in the interactive viewer.**

The **Repository Evidence** feature in `tt-a1i/archify` creates an immutable audit trail between every component in your architecture diagram and the exact source code that implements it. This guide shows you how to enable verification, structure your diagram JSON, and use the CLI to produce diagrams with traceable source beacons.

---

## What Repository Evidence Provides

When enabled, Archify performs three verification steps before rendering:

1. **Git checkout validation** — confirms the local repository's origin URL matches `repoUrl` and HEAD matches `repoCommit`
2. **Source file verification** — reads each declared blob from the verified commit and confirms unchanged state
3. **Source beacon embedding** — adds `SRC n` badges to the interactive viewer and `Semantic Passport` links to GitHub source lines

These badges appear **only in the viewer**; PNG, SVG, WebM, and Share Card exports strip them to keep artifacts self-contained. If any verification fails, Archify aborts with a structured diagnostic explaining the mismatch.

---

## Required CLI Flag and Repository Metadata

### The `--repo-root` Parameter

Every command that needs evidence requires `--repo-root <path>` pointing to your local checkout. According to the source at `bin/archify.mjs`, this flag triggers the verification pipeline.

```bash
node bin/archify.mjs render architecture diagram.json \
  --repo-root /path/to/archify \
  --quality showcase --json

```

The same flag applies to `validate`, `deliver`, `preview`, and `compare` commands.

### JSON Structure for Repository Evidence

Your architecture diagram must include three metadata fields documented in [[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md#L71-L73) (lines 71-73) and the [[`authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/authoring-contract.md)](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) reference:

```json
{
  "type": "architecture",
  "meta": {
    "quality_profile": "showcase",
    "repoUrl": "https://github.com/tt-a1i/archify",
    "repoCommit": "a73047b27e3b423fc8ab6ebd1ac84fd4ecb2e782"
  },
  "components": [
    {
      "id": "api",
      "kind": "backend",
      "label": "API Server",
      "sources": [
        { "path": "src/api/server.ts", "lines": "1-120" }
      ]
    },
    {
      "id": "db",
      "kind": "database",
      "label": "PostgreSQL",
      "sources": [{ "path": "sql/schema.sql" }]
    }
  ],
  "relationships": [
    { "source": "api", "target": "db", "kind": "call" }
  ]
}

```

| Field | Requirement |
|-------|-------------|
| `repoUrl` | Public HTTPS URL of the repository |
| `repoCommit` | Full 40-character SHA (no abbreviations) |
| `sources[].path` | Repository-relative file path |
| `sources[].lines` | Optional line range (e.g., `"47-89"` or `"12"` for single line) |

Each component can declare multiple sources; the badge shows `SRC n` where `n` is the count.

---

## CLI Workflow: Validate, Render, Deliver

Archify separates repository evidence into three command stages:

### 1. Validate (CI-Friendly)

Check diagram syntax and repository evidence without producing output:

```bash
node bin/archify.mjs validate architecture diagram.json \
  --repo-root /path/to/archify \
  --quality showcase --json

```

Returns structured diagnostics for any mismatch. Designed for **GitHub Actions, GitLab CI, or pre-commit hooks**.

### 2. Render (Preview with Evidence)

Generate the diagram with source badges attached:

```bash
node bin/archify.mjs render architecture diagram.json \
  --repo-root /path/to/archify \
  --quality showcase --json

```

Produces JSON output describing the rendered artifact; badges visible in subsequent viewer.

### 3. Deliver (Final Artifact)

Write the HTML file with embedded evidence metadata:

```bash
node bin/archify.mjs deliver architecture diagram.json \
  output.html \
  --repo-root /path/to/archify \
  --quality showcase --json

```

The [`output.html`](https://github.com/tt-a1i/archify/blob/main/output.html) contains the complete viewer with working source links.

---

## Using Evidence in the Interactive Viewer

After successful delivery:

1. **Hover** any node — a small `SRC n` badge appears in the upper-right corner
2. **Click** the node — the *Semantic Passport* panel opens with a direct link like:
   ```

   https://github.com/tt-a1i/archify/blob/a73047b27e3b423fc8ab6ebd1ac84fd4ecb2e782/src/api/server.ts#L1-L120
   ```

3. **Export** to PNG/SVG/WebM — badges are stripped automatically; the image contains no external references

This fail-closed design ensures **published screenshots cannot break** while **live diagrams remain fully traceable**.

---

## Troubleshooting Verification Failures

| Error | Cause | Fix |
|-------|-------|-----|
| `repoUrl mismatch` | Local origin differs from JSON | Run `git remote set-url origin <repoUrl>` or update `repoUrl` |
| `repoCommit mismatch` | HEAD SHA differs from JSON | Checkout the exact commit or update `repoCommit` |
| `source not found` | File path incorrect or deleted | Verify `path` is relative to repository root and exists at that commit |
| `source modified` | Working tree differs from commit | Commit changes or stash before running |

All errors include the **expected** and **actual** values for comparison.

---

## Key Source Files in the Repository

- **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)** (lines 71-73) — skill contract defining the `authoring-contract` schema for repository evidence fields
- **[`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md)** — authoritative payload specification for `repoUrl`, `repoCommit`, and `sources`
- **[`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md)** (lines 19-20) — feature announcement for *Revision-verified Repository Evidence Passport*
- **`bin/archify.mjs`** — CLI entry point implementing `--repo-root` flag and verification orchestration

---

## Summary

- **Repository Evidence** links Archify diagram nodes to exact source commits via SHA-verified Git references
- Enable with `--repo-root <path>` on `validate`, `render`, `deliver`, `preview`, or `compare` commands
- Declare evidence in diagram JSON using `meta.repoUrl`, `meta.repoCommit`, and per-component `sources` arrays
- Verification runs **fail-closed** — any mismatch aborts with specific diagnostics
- Source badges appear **only in the interactive viewer**, not in exported images
- Reference the [`authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/authoring-contract.md) specification for field-level documentation

---

## Frequently Asked Questions

### How do I update a diagram when the code changes?

Update the `repoCommit` field in your diagram JSON to the new SHA, then re-run your Archify commands. The verification ensures you explicitly acknowledge the code change rather than silently drifting from the documented state.

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

Yes — the verification uses your local Git checkout, so private repos work identically. The `repoUrl` should still be a reachable URL (even if private) so the Semantic Passport link resolves for viewers with access.

### What happens if I forget `--repo-root`?

Commands run without repository evidence checks. Diagrams render but show no `SRC` badges and contain no source links. To enforce evidence in CI, add `--repo-root` to your required command template.

### Why are source badges stripped from exports?

Per the [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md) and source implementation, exported formats (PNG, SVG, WebM, Share Cards) intentionally exclude badges to prevent broken links in static artifacts. The HTML viewer remains the canonical source-evidence experience.