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

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.

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#L71-L73) (lines 71-73) and the [authoring-contract.md](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) reference:

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

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:

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:

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

The 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 (lines 71-73) — skill contract defining the authoring-contract schema for repository evidence fields
• archify/references/authoring-contract.md — authoritative payload specification for repoUrl, repoCommit, and sources
• 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 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 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.

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