How to Link Git Repository Evidence to Architecture Diagrams with Source Code Details

Archify enriches architecture diagrams with immutable source-code evidence by adding SRC badges to repository-scanned nodes, enabling one-click navigation to exact file and line ranges on GitHub.

When you need to prove that an architecture diagram accurately reflects production code, manual documentation quickly becomes stale. Archify solves this by embedding source evidence directly into diagram nodes, creating an unbreakable link between visual architecture and the underlying Git repository. This traceability ensures that every component in your diagram is verifiable against a specific, immutable commit.

Understanding the Source Evidence Workflow

Archify’s evidence-linking system operates through a pipeline that scans repositories, extracts semantic metadata, and renders interactive badges in the viewer.

Repository Scanning and Validation

The process begins with the Archify CLI. When you run archify.mjs with the --repo flag, the tool fetches the repository, validates its structure, and produces a typed JSON Intermediate Representation (IR).

The CLI command structure follows this pattern:

node archify/bin/archify.mjs \
  analyse \
  --repo https://github.com/owner/repo \
  --commit <commit-hash> \
  --type architecture \
  --out diagram.html

This scan analyzes the codebase and generates nodes that carry provenance metadata. According to the authoring contract defined in [archify/references/authoring-contract.md](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md#L211), each node originating from source code receives a semantic passport containing repoUrl, commit, path, and range fields.

The SRC Badge and Semantic Passport

Once the IR is generated, Archify marks evidence-backed nodes with a sourceMarker field set to "SRC". The viewer renders this marker as a small SRC n badge in the node’s upper-right corner.

The badge text is localized through the i18n dictionary key viewer.passport.sourceMarker, defined in archify/renderers/shared/i18n.mjs. When you click this badge, the viewer constructs a precise GitHub URL using the stored passport data:

https://github.com/<owner>/<repo>/blob/<commit>/<path>#L<start>-L<end>

This opens the exact file and line range in a new browser tab, guaranteeing that the diagram remains traceable to immutable source code.

Implementing Source Links in Practice

You can generate evidence-backed diagrams through multiple interfaces: the command line, programmatic Node.js API, or interactive web viewer.

Command Line Repository Analysis

To generate a diagram with embedded source evidence, use the CLI with a specific commit hash:

# Scan the repository at a pinned commit to ensure immutability

node archify/bin/archify.mjs \
  analyse \
  --repo https://github.com/mco-org/mco \
  --commit 9f1a1cf \
  --type architecture \
  --out mco-runtime.architecture.html

This produces an HTML file where nodes derived from the scanned repository display the SRC badge.

Resulting Data Structure

The generated IR contains nodes with complete provenance metadata. Here is an excerpt showing the passport structure:

{
  "id": "node-42",
  "label": "AuthService",
  "kind": "Backend",
  "sourceMarker": "SRC",
  "passport": {
    "repoUrl": "https://github.com/mco-org/mco",
    "commit": "9f1a1cf",
    "path": "src/auth/service.ts",
    "range": "12-34"
  }
}

The passport object stores the immutable coordinates needed to reconstruct the source URL, while sourceMarker signals the viewer to render the badge.

Programmatic Node.js API

For automated workflows, you can invoke the analysis programmatically:

import { analyseRepo } from 'archify';

const ir = await analyseRepo({
  repo: 'https://github.com/mco-org/mco',
  commit: '9f1a1cf',
  diagram: 'architecture',
});

// ir.nodes contains objects with sourceMarker and passport fields
console.log(ir.nodes[0].passport);

This returns the same typed IR structure without spawning a separate CLI process.

Viewer Interaction Implementation

The viewer template at [archify/assets/template.html](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html#L7509) handles the click interaction. When a user clicks the SRC badge, the following logic executes:

// Runtime behavior in the Archify viewer
badge.addEventListener('click', () => {
  const { repoUrl, commit, path, range } = node.passport;
  const url = `${repoUrl}/blob/${commit}/${path}#L${range.start}-L${range.end}`;
  window.open(url, '_blank');
});

This construction matches the GitHub permalink format, ensuring compatibility with any public or private GitHub repository.

Export Behavior and Badge Visibility

The SRC badge serves an interactive purpose and is therefore viewer-only. When you export diagrams to static formats (PNG, SVG, or WebM), Archify strips the source markers to maintain clean visual artifacts while preserving the underlying evidence in the interactive HTML version.

This separation ensures that:

• Interactive viewers maintain full audit trails with clickable source links
• Static exports remain uncluttered for presentation decks or documentation
• Compliance requirements are met through immutable, version-controlled evidence

The badge insertion logic is validated by the test suite in archify/test/repository-evidence.test.mjs, ensuring consistent behavior across repository types.

Summary

• Archify links diagrams to source code by scanning Git repositories and embedding commit-specific metadata into node passports.
• The SRC badge appears in the viewer’s upper-right corner of evidence-backed nodes, fetched from the i18n key viewer.passport.sourceMarker in archify/renderers/shared/i18n.mjs.
• Clicking the badge constructs a GitHub permalink using repoUrl, commit, path, and range from the semantic passport defined in the authoring contract.
• Static exports exclude badges, keeping PNG/SVG outputs clean while the HTML viewer retains full traceability.
• No additional parsing is required after the initial scan, as all evidence is stored in the verified JSON payload.

Frequently Asked Questions

How does Archify ensure the source evidence remains accurate over time?

Archify pins every evidence link to a specific Git commit hash stored in the node's passport.commit field. Because Git commits are immutable, the permalink constructed by the viewer always points to the exact code state that existed during the scan, even if the repository’s main branch evolves. This guarantees that your architecture diagram remains auditable against historical code versions.

Can I use Archify with private GitHub repositories?

Yes. The viewer constructs standard GitHub URLs using the repoUrl stored in the semantic passport. If the viewer has access to the private repository (through browser authentication or VPN), clicking the SRC badge will successfully navigate to the private file. The URL format remains identical: https://github.com/<owner>/<repo>/blob/<commit>/<path>#L<start>-L<end>.

What happens if a node represents code from multiple files?

Each node in Archify’s IR contains a single passport object with one path and range. If an architectural component spans multiple files, the scanning logic typically selects the primary definition file (such as the main class or service entry point). The SRC badge links to that specific file and line range, providing the authoritative source of truth for that component.

Why is the SRC badge missing from my exported PNG file?

Archify intentionally strips the SRC badge from static exports (PNG, SVG, WebM) to maintain clean visual presentation. The badge only renders in the interactive HTML viewer where it serves a functional purpose. The underlying passport data remains available in the HTML file, ensuring that evidence is preserved in the interactive format while static images remain suitable for presentations.

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