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

> Explore how Archify verifies diagram nodes against source code artifacts. Learn about JavaScript checks for repository URL, commit hash, file, and line number validity.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-14

---

**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】:

```html
<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】:

```html
<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:

```javascript
// 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:

```html
<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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.