How to Enable Git Integration for Source Evidence Linking in Archify

Archify generates clickable Git links in architecture diagrams when you embed repository metadata and file coordinates in the diagram's JSON payload, enabling instant navigation from visual nodes to exact lines of source code.

Archify's source evidence linking feature transforms static architecture diagrams into interactive documentation by connecting nodes directly to specific lines in your Git repository. By configuring the repository metadata and mapping nodes to source files, the Archify viewer renders interactive beacons that resolve to deep links on GitHub.

Configure Repository Metadata in the Diagram JSON

To activate Git integration, you must supply a repository object in the diagram's root JSON. This metadata tells the viewer how to construct URLs pointing to specific commits in your version control system.

Required Repository Fields

According to the Archify source code, the repository object requires three fields:

• url – The HTTPS URL of the repository (e.g., https://github.com/your-org/your-repo)
• revision – The full 40-character commit SHA that the diagram was generated from
• shortRevision – The abbreviated 7-character SHA displayed in the UI (optional but recommended)

As implemented in tt-a1i/archify, this configuration appears in the runtime HTML output at line 4964 of the MCO showcase example:

{
  "schemaVersion": 1,
  "verified": true,
  "repository": {
    "url": "https://github.com/mco-org/mco",
    "revision": "9f1a1cf1afdc04d7b5406782b40dfec76d9bc798",
    "shortRevision": "9f1a1cf"
  }
}

Map Diagram Nodes to Source Files

Once repository metadata is defined, individual diagram nodes must declare their relationship to source code using the sources array. Each entry in this array creates a clickable link to a specific file and line range.

Defining Source References

Each source object within a node's sources array must contain:

• path – Relative path from repository root to the source file
• line – Starting line number (integer)
• endLine – Optional ending line number for ranges
• label – Human-readable description displayed in the UI

The viewer combines the repository.url, repository.revision, path, and line numbers to construct the final GitHub URL using the standard /blob/ pattern.

Example node definition from the MCO showcase (mco-runtime.html#L4964):

{
  "id": "entry",
  "type": "start",
  "label": "Entry Point",
  "sources": [
    {
      "path": "bin/mco.js",
      "line": 1,
      "label": "npm entry"
    }
  ]
}

Serve the Diagram with the Archify Viewer

The Archify viewer processes the JSON payload and injects interactive elements into the rendered SVG. This functionality requires specific HTML structure and CSS rules included in the viewer template.

Embedding the Payload

In scripts/start-template.html, the diagram data—including the repository metadata—must be embedded in a script element with the ID archify-source-evidence-data:

<script id="archify-source-evidence-data"
        type="application/json">
  {
    "schemaVersion": 1,
    "verified": true,
    "repository": {
      "url": "https://github.com/example/project",
      "revision": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t",
      "shortRevision": "a1b2c3d"
    },
    "nodes": [
      {
        "id": "api",
        "type": "service",
        "label": "API",
        "sources": [
          { "path": "src/api/server.ts", "line": 12, "label": "Server entry" }
        ]
      }
    ]
  }
</script>

Rendering Source Evidence Beacons

The viewer reads the JSON payload, validates the repository information, and injects source-evidence beacons into the SVG. These beacons appear when users hover over nodes and trigger navigation when clicked.

The styling and positioning logic resides in the source-evidence-beacon CSS rules found at lines 4085–4111 of the runtime HTML file. The viewer script generates anchor tags that resolve to URLs following the pattern:

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

Verify the Integration

To ensure Git integration functions correctly, the Archify test suite includes automated validation in archify/test/story-moment-link.test.mjs. This test verifies that the viewer correctly resolves repository links to the expected Git commit and line range.

Automated Testing Example

The following test snippet validates that source evidence links resolve to the correct GitHub URLs:

import { test } from 'uvu';
import * as assert from 'uvu/assert';
import { renderDiagram } from '../archify/viewer.js';

test('source evidence link resolves to GitHub', async () => {
  const diagram = await renderDiagram('my-diagram.json');
  const beacon = diagram.querySelector('[data-source-evidence-beacon]');
  const href = beacon.querySelector('a').href;
  assert.is(
    href,
    'https://github.com/example/project/blob/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t/src/api/server.ts#L12'
  );
});

test.run();

Executing this test confirms that the repository URL, revision SHA, and file paths concatenate correctly to form valid GitHub links.

Summary

• Repository configuration requires three fields: HTTPS URL, full commit SHA (revision), and abbreviated SHA (shortRevision) embedded in the diagram JSON root.
• Node-level source mapping uses the sources array, containing objects with path, line, endLine, and label properties to pinpoint exact code locations.
• The Archify viewer in scripts/start-template.html reads the JSON payload from the <script id="archify-source-evidence-data"> element and renders interactive beacons via CSS rules defined at lines 4085–4111.
• Automated validation through archify/test/story-moment-link.test.mjs ensures links resolve to the correct Git commit and line numbers.

Frequently Asked Questions

What fields are required in the repository object for Git integration?

The repository object must include url (the HTTPS repository URL) and revision (the full 40-character commit SHA). The shortRevision field is optional but recommended for cleaner UI display. All three fields are validated by the viewer before rendering source evidence beacons.

Can I link to a range of lines rather than a single line?

Yes. Include both line and endLine properties in the source object. The Archify viewer constructs URLs using the standard GitHub line range format (e.g., #L12-L15), allowing users to view multi-line code blocks directly in the repository interface.

How do I verify that source evidence links are working correctly?

Run the test suite in archify/test/story-moment-link.test.mjs, which validates that the viewer correctly resolves repository metadata and file paths into clickable GitHub URLs. Alternatively, open the generated HTML in a browser, hover over diagram nodes to reveal beacons, and confirm that clicking navigates to the correct commit and line number.

Where is the CSS styling for source evidence beacons defined?

The visual styling and positioning rules for source evidence beacons reside in the source-evidence-beacon CSS classes within the runtime HTML output. In the MCO showcase example (mco-runtime.html), these rules appear at lines 4085–4111 and control the hover behavior and visual appearance of the clickable link indicators.

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