How Source Evidence Verification Works in Archify: A Technical Deep Dive

Archify verifies every diagram node against concrete source-code artifacts by embedding a JSON payload in a hidden <script> element and running JavaScript checks for repository URL, commit hash, file existence, and line number validity.

Archify is an open-source tool that generates architecture diagrams directly from code. Its source evidence verification system ensures that every visual element in a diagram maps to a real, version-locked line of code—eliminating "stale diagram" problems that plague technical documentation.

The Source Evidence Data Structure

Every rendered Archify diagram contains a hidden JSON payload that defines the verifiable source locations for each node. According to the archify source code, this data lives in a <script id="archify-source-evidence-data"> element with the following schema【source‑evidence‑data line 4505】:

<script id="archify-source-evidence-data" type="application/json">
{
  "schemaVersion": 1,
  "verified": true,
  "repository": {
    "url": "https://github.com/mco-org/mco",
    "revision": "9f1a1cf…"
  },
  "referenceCount": 14,
  "nodes": {
    "entry": [
      {
        "path": "bin/mco.js",
        "line": 1,
        "label": "npm entry",
        "href": "https://github.com/mco-org/mco/.../bin/mco.js#L1"
      }
    ],
    "router": [
      {
        "path": "runtime/cli.py",
        "line": 1945,
        "label": "CLI main",
        "href": "https://github.com/mco-org/mco/.../runtime/cli.py#L1945"
      }
    ]
  }
}
</script>

The nodes object maps node IDs to arrays of source entries, each containing:

• path — relative file path within the repository
• line — exact line number or start of range
• label — human-readable description for the UI
• href — direct link to the source in the repository browser

Three-Stage Verification Process

When the diagram renders in the browser, Archify's runtime JavaScript performs three sequential validation checks【source‑evidence‑data line 4505】:

1. Repository and Commit Matching

The code verifies that the current checkout matches the recorded repository.url and repository.revision. This prevents diagrams from falsely claiming verification against a different code state.

2. File Existence Validation

Each path in the sources array is checked against the repository tree at the specified revision. Missing files immediately invalidate the node's evidence status.

3. Line Number Bounds Checking

The line field is validated against the actual file length. References beyond EOF are rejected.

If any check fails, the node is marked as missing evidence and the "Verified source" badge is suppressed.

The Source Evidence Beacon System

For nodes that pass verification, Archify injects beacon markers into the DOM【source‑evidence‑beacon line 6957‑6980】:

<div data-node-id="router"
     data-source-evidence-beacon
     data-source-evidence-count="1"
     data-source-evidence-original-label="CLI main">
</div>

These data attributes serve specific purposes:

Attribute	Purpose
data-source-evidence-beacon	Boolean marker indicating verified status
data-source-evidence-count	Number of source references for this node
data-source-evidence-original-label	Preserved label for the evidence panel

Rendering the Verified Source UI

The runtime loops over all beacon-marked elements and populates a hidden evidence pane【source‑evidence‑beacon line 7012‑7358】. The relevant JavaScript structure:

// Extracted from the Archify runtime (approx. lines 6926-6980)
var element = document.getElementById('archify-source-evidence-data');
var sources = JSON.parse(element.textContent).nodes;

Object.entries(sources).forEach(([nodeId, entries]) => {
  var node = document.querySelector(`[data-node-id="${nodeId}"]`);
  
  // Skip if already processed or node missing
  if (!node || node.querySelector('[data-source-evidence-beacon]')) {
    return;
  }
  
  // Verification logic: repo URL, revision, file existence, line range
  
  var beacon = document.createElement('div');
  beacon.classList.add('source-evidence-beacon');
  beacon.setAttribute('data-source-evidence-beacon', '');
  node.appendChild(beacon);
  
  node.setAttribute('data-source-evidence-count', entries.length);
});

The evidence list renders into:

<ul class="include-list" id="include-list" aria-label="Required evidence">
  <!-- Populated dynamically from verified sources -->
</ul>

This placeholder exists in scripts/start-template.html【source‑evidence‑list line 265】.

Key Files in the Verification Pipeline

File Path	Role in Source Evidence Verification
scripts/start-template.html	Contains the <ul id="include-list"> evidence list placeholder
scripts/run-tests.mjs	Runs smoke tests asserting evidence verification passes【package‑smoke line 193‑195】
examples/workflow-agent-tool-call-rendered.html	Full demonstration of hidden evidence pane and beacon handling【workflow‑agent‑tool‑call‑rendered line 5229‑7358】
Embedded archify-source-evidence-data script tags	JSON payload storage driving all verification
Template-embedded rendering JavaScript	Beacon injection, validation, and UI population【source‑evidence‑beacon line 6926‑7358】

Summary

• Source evidence verification in Archify binds every diagram node to specific, version-locked code locations through a JSON payload embedded in the rendered HTML.
• Three validation checks ensure repository URL, commit hash, file existence, and line number bounds all match before marking a node verified.
• Beacon attributes (data-source-evidence-beacon, data-source-evidence-count) enable the runtime to render clickable, human-readable source links.
• Template-driven architecture places evidence data and rendering logic directly in generated HTML, making diagrams self-contained and portable.

Frequently Asked Questions

How does Archify prevent stale diagram references?

Archify embeds a commit hash in every diagram's source evidence data. The runtime verifies this hash against the current checkout; mismatches suppress the "Verified source" badge, alerting viewers to potential drift between diagram and code.

Can source evidence verification work with private repositories?

Yes. The verification system checks against any repository URL in the archify-source-evidence-data payload. For private repos, the href fields in the JSON would point to internal git hosts, and file existence validation would require appropriate authentication in the browsing context.

What happens when a source file is moved or renamed?

The file existence check fails during rendering. The node loses its data-source-evidence-beacon attribute and the "Verified source" badge disappears. Regenerating the diagram from the current code state updates the evidence data with new paths.

Where is the verification logic tested?

The scripts/run-tests.mjs file contains smoke tests that assert evidence verification passes for generated diagrams【package‑smoke line 193‑195】, ensuring the beacon injection and JSON parsing logic remains functional across releases.

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