How to Add Source Evidence Links to Archify Architecture Nodes Using Git-Verified Files

Annotate Archify architecture nodes with Git-verified source links by declaring repository metadata in your diagram's meta section, adding sources arrays to components, and rendering with --repo-root for automatic verification.

Archify supports source-evidence linking—a feature that pins architecture nodes to exact files and line ranges in a public GitHub repository. This process validates every reference against a local checkout before rendering, ensuring immutable, trustworthy documentation. Below is the complete workflow for adding Git-verified source evidence links to your Archify diagrams.

Prerequisites for Source-Evidence Linking

Before you begin, you need:

• A public GitHub repository URL
• A full 40-character commit SHA to pin evidence immutably
• A local clone of that repository on the machine running Archify

The verification logic in archify/renderers/shared/repository-evidence.mjs enforces these requirements strictly—short SHAs or unverified remotes will fail.

Step 1: Declare Repository Metadata in the Diagram

Every diagram supporting source evidence must include a meta.repository object. This tells Archify where to build GitHub permalinks and which commit to pin.

{
  "meta": {
    "title": "My Service Architecture",
    "repository": {
      "url": "https://github.com/tt-a1i/archify",
      "revision": "2a9c3f5c0e8bdfd4e7b4e2b1a5f6c4c7d9f8e1e2"
    }
  },
  "components": []
}

As implemented in archify/renderers/shared/repository-evidence.mjs lines 94-100, the revision must be a complete SHA—no tags or abbreviated hashes. This guarantees immutable evidence: the link will always point to exactly that commit, even if the branch moves forward.

Step 2: Add Sources Arrays to Components

Within any component definition, include a sources array. Each entry specifies a repo-relative POSIX path, optional line numbers, and a human-readable label.

{
  "id": "api-gateway",
  "type": "service",
  "label": "API Gateway",
  "sources": [
    {
      "path": "src/gateway/main.py",
      "line": 45,
      "end_line": 89,
      "label": "Request routing logic"
    },
    {
      "path": "src/gateway/config.yaml",
      "label": "Configuration schema"
    }
  ]
}

The sourceHref function (lines 68-73 in repository-evidence.mjs) transforms these entries into GitHub permalinks. Use line for single-line references; add end_line for ranges. Omit both for file-level links.

Step 3: Validate Path Syntax

The verifiedSourcePath validator (lines 47-65 in repository-evidence.mjs) enforces strict path rules:

• Repo-relative only: Paths must not start with / or include absolute prefixes
• POSIX format: Forward slashes (/); backslashes are rejected
• No traversal: .. and .git segments are blocked to prevent repository escape
• No null bytes or other dangerous characters

Invalid paths trigger immediate validation errors with diagnostic messages before Git verification even begins.

Step 4: Render with --repo-root for Verification

Execute Archify with the --repo-root flag pointing to your local clone:

node archify/bin/archify.mjs render architecture diagram.json \
  --out diagram.html \
  --repo-root /home/user/projects/archify

The CLI entry point (archify/bin/archify.mjs) invokes verifyRepositoryEvidence before rendering proceeds. Verification happens in three stages as implemented in lines 87-119 of repository-evidence.mjs:

1. Git-origin check: Confirms the local clone's remote matches meta.repository.url (see getRepositoryRemotes, lines 40-47)
2. SHA existence: Runs git cat-file -e to verify the commit exists
3. File validation: Executes git cat-file -t to confirm each path points to a blob (file), not a tree or missing object

Optional line-range sanity checks ensure line ≤ end_line when both are present.

Step 5: Evidence Embedding and UI Rendering

Upon successful verification, two embedding steps occur:

Server-side injection: The applyTemplate function in archify/renderers/shared/utils.mjs (lines 115-122) injects a <script id="archify-source-evidence-data"> block containing the verified JSON payload.

Client-side beacons: The HTML template (archify/assets/template.html, line 6816) initializes Archify.sourceEvidence.installBeacons(), which reads the payload and renders clickable indicators on each node. Clicking a beacon opens the GitHub file at the exact line range.

Complete Working Example

Save this as api-service.json:

{
  "meta": {
    "title": "API Service with Evidence",
    "repository": {
      "url": "https://github.com/tt-a1i/archify",
      "revision": "2a9c3f5c0e8bdfd4e7b4e2b1a5f6c4c7d9f8e1e2"
    }
  },
  "components": [
    {
      "id": "cli",
      "type": "process",
      "label": "CLI Tool",
      "sources": [
        {
          "path": "archify/bin/archify.mjs",
          "line": 15,
          "label": "Entry point"
        }
      ]
    },
    {
      "id": "verifier",
      "type": "process",
      "label": "Evidence Verifier",
      "sources": [
        {
          "path": "archify/renderers/shared/repository-evidence.mjs",
          "line": 94,
          "end_line": 112,
          "label": "Core verification logic"
        }
      ]
    },
    {
      "id": "template-utils",
      "type": "service",
      "label": "Template Utilities",
      "sources": [
        {
          "path": "archify/renderers/shared/utils.mjs",
          "line": 115,
          "end_line": 122,
          "label": "Evidence injection"
        }
      ]
    }
  ],
  "edges": [
    { "from": "cli", "to": "verifier", "label": "triggers" },
    { "from": "verifier", "to": "template-utils", "label": "populates" }
  ]
}

Render and verify:

git clone https://github.com/tt-a1i/archify.git
cd archify
git checkout 2a9c3f5c0e8bdfd4e7b4e2b1a5f6c4c7d9f8e1e2

node archify/bin/archify.mjs render architecture api-service.json \
  --out api-service.html \
  --repo-root .

The output api-service.html displays clickable source-evidence beacons on all three nodes. The "Evidence Verifier" node links directly to the verification implementation—meta-documentation that verifies itself.

Error Handling and Diagnostics

If verification fails, Archify aborts rendering and emits structured errors. The evidenceFailure helper (lines 9-17 in repository-evidence.mjs) includes a supportedFixes array suggesting corrective actions:

• Remote mismatch → Check meta.repository.url against git remote -v
• Missing commit → Verify SHA exists with git cat-file -e <sha>
• Missing file → Confirm path is repo-relative and committed
• Invalid line range → Ensure line ≤ end_line and both are positive integers

Key Implementation Files

File	Purpose
archify/renderers/shared/repository-evidence.mjs	Core verification: hasRepositoryEvidence, verifyRepositoryEvidence, sourceHref, verifiedSourcePath
archify/renderers/shared/utils.mjs	HTML injection via applyTemplate (lines 115-122)
archify/assets/template.html	Client-side beacon rendering (line 6816)
archify/bin/archify.mjs	CLI orchestration and verification trigger

Summary

• Declare meta.repository with full GitHub URL and 40-character SHA
• Attach sources arrays to components with POSIX paths and optional line ranges
• Render with --repo-root pointing to a verified local clone
• Automatic verification checks remotes, commits, files, and line sanity via repository-evidence.mjs
• Embedded JSON payload enables clickable beacons linking to immutable GitHub locations

This workflow guarantees that every architecture node in your Archify diagrams connects to cryptographically verifiable source code—no drift, no broken links, no trust assumptions.

Frequently Asked Questions

What happens if the commit SHA is not in my local clone?

Archify fails fast with a descriptive error. The git cat-file -e check (line 96 in repository-evidence.mjs) confirms SHA existence before proceeding. Fetch the missing commit with git fetch origin <sha> or use a SHA present in your local repository.

Can I use source evidence with private repositories?

No. The sourceHref function builds github.com permalinks, and verification expects publicly resolvable URLs. Private repository support would require authentication token injection and is not implemented in the current codebase.

Why does Archify require a local clone instead of using the GitHub API?

Local verification eliminates API rate limits, supports air-gapped environments, and enables git cat-file blob type checks without network dependencies. The --repo-root approach also validates that you personally have access to the source, adding a trust anchor to the evidence chain.

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