How to Use Repository Evidence to Link Diagrams to Git Commits in Archify

Archify creates verified architecture diagrams by embedding a hidden JSON payload that maps every visual element to specific file paths, line ranges, and exact Git revision hashes, enabling direct navigation from diagrams to source code.

Linking visual architecture diagrams to concrete Git commits ensures your documentation stays auditable and trustworthy. In the tt-a1i/archify repository, this is achieved through a repository evidence workflow that ties each diagram node back to the exact lines of code that justify its existence. This process involves three tightly-coupled steps that validate and expose source references directly within the rendered output.

How Repository Evidence Works in Archify

The evidence system operates as a verification layer between your Git repository and the generated diagram. When Archify renders a visualization, it does not merely draw boxes and arrows—it injects provenance metadata that survives export to HTML and can be re-validated against future commits.

The workflow follows a strict pipeline: collect metadata → render visual beacons → expose human-readable checklists. Each step references specific source files in the Archify codebase that handle the heavy lifting of hash verification and DOM injection.

Step 1 – Collect Evidence Metadata

The foundation of traceable diagrams is a machine-readable evidence payload. In experiments/mco-showcase/mco-runtime.html at line 4504, Archify injects a hidden JSON blob inside a <script id="archify-source-evidence-data"> tag. This object records:

• The repository URL
• The exact Git revision hash (commit SHA)
• A structured list of source files with specific line ranges supporting each node and edge

The renderer only emits this payload after confirming the revision, blob, and line numbers are valid, as noted by the comment /* Verified repository evidence is emitted only after the renderer checks */ in the same file.

Step 2 – Render Evidence Beacons

Once metadata is collected, Archify surfaces it through interactive UI elements called evidence beacons. For each node with associated source entries, the system adds a data-source-evidence-beacon attribute to the SVG element, along with a data-source-evidence-count stamp showing the number of linked references.

The styling for these beacons appears in experiments/mco-showcase/mco-runtime.html around line 3642, while the JavaScript that creates the beacon elements and attaches hover handlers resides at line 6973. When users hover or focus a node, a pop-up with the class .semantic-passport-evidence displays clickable links that open the exact file and line range on GitHub (e.g., https://github.com/owner/repo/blob/<hash>/src/file.js#L42-L57).

Step 3 – Generate the Include List

Beyond visual beacons, Archify exposes the evidence through a reusable checklist UI. The template at scripts/start-template.html line 265 contains an empty <ul> element with the ID include-list. During diagram generation, Archify populates this list with the human-readable "Evidence to include" checklist that appears in the sidebar.

This same list powers the CLI's guide command output, allowing you to copy-paste evidence checklists directly into pull request descriptions or technical documentation.

Validating Evidence Against Repository State

The evidence data remains tethered to the specific commit hash captured during generation. When the repository advances, you can re-validate the diagram against the new revision. Archify flags any mismatches—such as line number drift or file renames—during the rendering step, preventing stale links from persisting in your documentation.

This validation ensures that clicking a beacon in a six-month-old diagram will still land on the correct historical commit, even if the file has moved or changed on the main branch.

Practical Implementation Example

Use the following CLI workflow to generate diagrams with full repository evidence linkage:

# Generate a diagram and capture evidence metadata

node archify/bin/archify.mjs guide \
  "Show an API request with JWT auth, a Redis cache miss, and async tracing" \
  --json > my-diagram.json

# Render as interactive HTML with evidence beacons enabled

node archify/bin/archify.mjs preview \
  my-diagram.json \
  ./my-diagram.html \
  --quality showcase

# Extract the evidence checklist for PR documentation

node archify/bin/archify.mjs guide \
  "Show an API request with JWT auth" \
  --list-evidence > evidence-checklist.txt

After running these commands, open my-diagram.html and hover any node to see pop-up links pointing to specific commits. The evidence checklist in evidence-checklist.txt contains the same references formatted for human review.

Key Source Files

The following files in the tt-a1i/archify repository implement the evidence linkage system:

• experiments/mco-showcase/mco-runtime.html (lines 4504, 3642, 6973): Contains the JSON payload injection, beacon CSS, and JavaScript beacon creation logic
• scripts/start-template.html (line 265): Hosts the include-list placeholder for the evidence checklist UI
• examples/maka-architecture.architecture.json: Demonstrates the JSON structure linking nodes to source files
• archify/SKILL.md: Documents the skill and renderer contract for evidence handling

Summary

• Repository evidence in Archify consists of a JSON payload containing repository URLs, commit hashes, and precise file-line mappings injected at experiments/mco-showcase/mco-runtime.html line 4504.
• Visual beacons (data-source-evidence-beacon) appear on diagram nodes and reveal clickable GitHub links via the pop-up mechanism defined at line 6973.
• The include-list element in scripts/start-template.html line 265 provides a human-readable evidence checklist for documentation and PR comments.
• Evidence is validated before emission, ensuring only accurate, traceable links survive into the final rendered output.
• The CLI commands guide and preview generate evidence-enriched diagrams that remain linked to specific Git commits regardless of subsequent repository changes.

Frequently Asked Questions

How does Archify verify that evidence links point to valid commits?

Archify validates repository evidence during the rendering phase before injecting the JSON payload. The renderer checks that the revision hash exists, that the blob references are reachable, and that the specified line numbers fall within valid ranges. Only after these checks succeed does the system emit the evidence data, as enforced by the verification logic in experiments/mco-showcase/mco-runtime.html.

Can I use repository evidence with private Git repositories?

Yes, the evidence system works with any Git URL, including private repositories. The generated HTML contains the repository URL and commit hash in plain text, but the clickable links respect your browser's authentication state. For private repos, ensure viewers have appropriate access rights to the Git hosting platform, as Archify generates standard HTTPS links that rely on the host's authentication flow.

What happens to evidence beacons when source files move or lines change?

Evidence beacons capture the commit hash at generation time, creating permanent links to that specific revision. If files move or lines change in later commits, the original evidence remains valid because it points to the historical commit. To update diagrams to reference the latest main branch, you must regenerate the diagram with Archify, which will capture the new HEAD hash and current line ranges.

How do I extract the evidence list without generating a full HTML preview?

Use the guide command with the --list-evidence flag to output only the evidence checklist without creating an HTML file. This command populates the same include-list structure used by the UI, making it ideal for CI pipelines or documentation generators that need to reference source locations without rendering interactive graphics.

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