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

> Link Git repository evidence to architecture diagrams using Archify. Add SRC badges to nodes for one-click navigation to GitHub source code and line ranges.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-11

---

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

```bash
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)](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`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/shared/i18n.mjs#L388). When you click this badge, the viewer constructs a precise GitHub URL using the stored passport data:

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

```bash

# 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:

```json
{
  "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:

```javascript
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)](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:

```javascript
// 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`](https://github.com/tt-a1i/archify/blob/main/archify/test/repository-evidence.test.mjs#L403), 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.