How Archify Uses Repository Evidence for Nodes: Source Verification and Interactive Beacons Explained

Archify enriches diagram nodes with repository evidence by verifying source code locations against the target repository before injecting provenance data into the rendered HTML as interactive beacons.

The architecture documentation tool Archify transforms static diagrams into auditable artifacts by binding each node to its originating source code. This process—repository evidence attachment—ensures that every element in a generated workflow diagram can be traced back to a specific file, revision, and line number in the underlying repository.

Repository Evidence Verification Pipeline

Archify does not blindly attach metadata. Before any evidence appears in the output, the renderer performs a validation sequence checking the revision, blob SHA, and line range of each referenced source location. Only after these checks pass does the system emit evidence data.

This guard appears in the generated HTML output:

/* Verified repository evidence is emitted only after the renderer checks */
if (!Array.isArray(sources) || !sources.length || node.querySelector('[data‑source‑evidence‑beacon]')) return;

Source: [generated/maka-regenerated.workflow.html](https://github.com/tt-a1i/archify/blob/main/generated/maka-regenerated.workflow.html#L7446-L7490)

Evidence Data Structure and Storage

Once verified, repository evidence is serialized into a hidden JSON payload. The <script> element with ID archify-source-evidence-data contains an array of provenance records, each specifying:

• Repository URL — the GitHub origin
• Revision — commit SHA or tag
• File path — relative path within the repository
• Line numbers — exact range for the referenced code
• Label — human-readable description of the source's role

This data structure appears around line 4964 in the generated output:

Source: [generated/maka-regenerated.workflow.html](https://github.com/tt-a1i/archify/blob/main/generated/maka-regenerated.workflow.html#L4964-L4965)

Node Attribute Injection

Archify marks each validated node with three data attributes that power the interactive experience:

Attribute	Purpose
data-source-evidence-beacon	Signals that the node carries verified evidence
data-source-evidence-count	Number of distinct source locations backing this node
data-source-evidence-original-label	Preserves the original node label for display context

These attributes enable CSS selectors and JavaScript handlers to identify evidential nodes without DOM traversal.

The Focus Evidence Panel

User interaction reveals the underlying source through a dedicated panel. The hidden container div.semantic-passport-evidence (ID focus-evidence) is populated dynamically when a node receives focus or hover:

<!-- Hidden panel that will show the verified source links -->
<div class="semantic-passport-evidence" id="focus-evidence" hidden>
  <div class="semantic-passport-evidence-head">
    <span class="semantic-passport-evidence-status">Verified source</span>
  </div>
  <div class="semantic-passport-evidence-links" id="focus-evidence-links"></div>
</div>

JavaScript transfers the appropriate link from the JSON evidence store into #focus-evidence-links, constructing canonical GitHub URLs in the format:

https://github.com/{owner}/{repo}/blob/{revision}/{path}#L{line}

Visual Styling and Beacon Rendering

CSS rules in the same generated file control the visual presentation:

• .source-evidence-beacon — styles the indicator icon appearing on evidential nodes
• .semantic-passidence-evidence — panel positioning and typography
• Hover states trigger opacity transitions and reveal animations

The beacon pattern ensures visual clutter is minimized while maintaining discoverability—users see the indicator only when it matters, then access full provenance on demand.

Summary

• Verification first — Archify validates repository revision, blob SHA, and line range before attaching any evidence
• Structured storage — Provenance data lives in hidden JSON (archify-source-evidence-data) with complete source coordinates
• Node marking — Three data attributes flag verified nodes for styling and interaction
• Interactive reveal — The focus-evidence panel displays clickable source links when users engage with diagram elements
• Traceable URLs — All evidence links resolve to exact file/line locations in the canonical repository

Frequently Asked Questions

What repository information does Archify attach to each node?

Archify attaches the repository URL, revision (commit SHA or tag), file path, line number range, and a descriptive label. This data is stored in the archify-source-evidence-data JSON script and surfaced through node attributes and the focus evidence panel.

How does Archify verify that source code exists before showing evidence?

The renderer checks that the source array is valid and non-empty, then confirms the node doesn't already carry evidence markup. This guard prevents duplicate or unverified evidence from appearing in the output, as implemented in lines 7446–7490 of the generated workflow HTML.

Can users click through from a diagram node to the actual source code?

Yes. When a user focuses or hovers a node with evidence, Archify populates the #focus-evidence-links container with anchor elements pointing directly to https://github.com/{owner}/{repo}/blob/{revision}/{path}#L{line}. These links open the exact source location in the repository.

What happens if repository verification fails for a source location?

The guard condition returns early without attaching evidence attributes. Nodes without verified sources render normally but lack the data-source-evidence-beacon marker and do not appear in the interactive evidence panel.

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