# How Archify Pins Diagram Nodes to Git‑Verified Source Files

> Archify pins diagram nodes to Git-verified source files by embedding Git commit metadata and source line references into generated HTML. Learn how Archify ensures traceable diagrams.

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

---

**Archify pins every diagram node to a specific Git commit by embedding a JSON payload containing repository metadata and source line references directly into the generated HTML via a `<script>` tag with the ID `archify-source-evidence-data`.**

Archify generates software architecture diagrams that remain permanently linked to the exact version of code that produced them. By **pinning diagram nodes to Git‑verified source files**, the tool ensures that every visual element can be traced back to a cryptographically anchored revision, preventing documentation drift and guaranteeing reproducibility.

## Collecting Git Metadata at Build Time

When Archify renders a diagram, it first captures the precise state of the repository. This process involves executing Git commands to establish an immutable reference point.

### Extracting Repository Identity

The system runs `git rev‑parse HEAD` to obtain the current commit SHA and records the repository URL. This information forms the foundation of the **source evidence** object, which is structured as a plain JSON payload following the schema `{ verified: true, repository: { url, revision }, referenceCount, nodes: { … } }`.

According to the [`archify/utils/git.js`](https://github.com/tt-a1i/archify/blob/main/archify/utils/git.js) helper module, this metadata extraction happens before any rendering begins, ensuring that the evidence reflects the exact state of the repository at build time.

## Mapping Nodes to Source Locations

For each visual node representing a concrete code artifact, Archify records precise location data. This mapping includes:

- The **file path** relative to the repository root
- The **starting line** and optional **ending line** for range references
- A human‑readable **label** describing the code element
- A direct **hyperlink** pointing to the specific line on the remote Git host (e.g., GitHub)

The assembled data structure associates every diagram element with its canonical source location, creating an auditable trail from visualization to implementation.

## Embedding Evidence in HTML Output

The verification payload is serialized and injected into the final HTML document during the template application phase. In `archify/renderers/shared/utils.mjs`, the `applyTemplate` function handles this insertion at lines 180‑182:

```javascript
// archify/renderers/shared/utils.mjs (lines 180-182)
const sourceEvidenceJson = serializeScriptJson(sourceEvidence);
…
.replace(SOURCE_EVIDENCE_PLACEHOLDER, () => sourceEvidence
    ? `    <script id="archify-source-evidence-data" type="application/json">${sourceEvidenceJson}</script>`
    : '');

```

The `SOURCE_EVIDENCE_PLACEHOLDER` marker in [`archify/renderers/shared/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/shared/template.html) (sourced from [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html)) is replaced with the serialized JSON script element. This embeds the evidence directly into the DOM, making it available for both human inspection and programmatic verification.

## Runtime Consumption and CI Verification

Once embedded, the source evidence serves two purposes: interactive navigation and automated validation.

### Front‑End Navigation

The Archify viewer parses the `archify-source-evidence-data` script tag at runtime. It extracts the `href` values from the JSON payload to generate clickable node anchors. When a user interacts with a diagram element, the viewer opens the exact line or range in the remote repository, ensuring the displayed code matches the **Git‑verified** revision.

### Continuous Integration Validation

Archify’s test suite enforces that every generated diagram contains valid source evidence. In `archify/bin/archify.mjs` at line 807, the CI pipeline extracts and validates the embedded script:

```javascript
// archify/bin/archify.mjs (line 807)
const match = html.match(
  /<script id="archify-source-evidence-data" type="application\/json">([\s\S]*?)<\/script>/,
);
assert.ok(match, 'source‑evidence script is present');
const sourceEvidence = JSON.parse(match[1]);
assert.equal(sourceEvidence.verified, true);

```

The tests in `archify/test/real-repository-proof.test.mjs` and `archify/test/repository-evidence.test.mjs` further verify that the JSON contains the `verified: true` flag, a valid repository URL, and correct node references.

## Practical Implementation Example

To generate a diagram with pinned source evidence, pass a structured evidence object to the render function:

```javascript
import { renderDiagram } from 'archify';
import { getGitInfo } from 'archify/utils/git';

const gitInfo = await getGitInfo(); 
// { url: 'https://github.com/tt-a1i/archify', revision: 'a1b2c3d' }

const sourceEvidence = {
  verified: true,
  repository: { 
    url: gitInfo.url, 
    revision: gitInfo.revision 
  },
  referenceCount: 2,
  nodes: {
    entry: [
      {
        path: 'src/main.js',
        line: 42,
        label: 'Main entry point',
        href: `${gitInfo.url}/blob/${gitInfo.revision}/src/main.js#L42`,
      },
      {
        path: 'src/util.js',
        line: 10,
        endLine: 15,
        label: 'Utility function',
        href: `${gitInfo.url}/blob/${gitInfo.revision}/src/util.js#L10-L15`,
      },
    ],
  },
};

const html = await renderDiagram({
  title: 'Example Architecture',
  svg: '<svg>…</svg>',
  sourceEvidence,  // Passed to applyTemplate for embedding
});

```

The resulting HTML contains the embedded verification data:

```html
<script id="archify-source-evidence-data" type="application/json">
{
  "verified": true,
  "repository": {
    "url": "https://github.com/tt-a1i/archify",
    "revision": "a1b2c3d"
  },
  "referenceCount": 2,
  "nodes": {
    "entry": [
      {
        "path": "src/main.js",
        "line": 42,
        "label": "Main entry point",
        "href": "https://github.com/tt-a1i/archify/blob/a1b2c3d/src/main.js#L42"
      },
      {
        "path": "src/util.js",
        "line": 10,
        "endLine": 15,
        "label": "Utility function",
        "href": "https://github.com/tt-a1i/archify/blob/a1b2c3d/src/util.js#L10-L15"
      }
    ]
  }
}
</script>

```

## Summary

- **Archify** generates architecture diagrams that embed Git verification metadata directly into HTML output.
- The `applyTemplate` function in `archify/renderers/shared/utils.mjs` inserts a JSON payload with the ID `archify-source-evidence-data` containing commit SHAs, repository URLs, and exact line references.
- Each diagram node maps to a specific file path and line range, creating permanent hyperlinks to the source code.
- The CI pipeline validates the presence of `verified: true` and correct repository evidence in `archify/bin/archify.mjs` to ensure documentation integrity.
- This approach guarantees that every diagram remains traceable to a specific, immutable Git revision.

## Frequently Asked Questions

### What is the JSON schema for source evidence in Archify?

The source evidence follows a strict schema containing a `verified` boolean flag, a `repository` object with `url` and `revision` strings, a `referenceCount` integer, and a `nodes` object that maps diagram elements to arrays of location objects. Each location object includes `path`, `line`, optional `endLine`, `label`, and `href` properties pointing to the exact source lines.

### How does Archify verify the Git commit during the rendering process?

During rendering, Archify executes Git commands via the utility module to capture the current commit SHA and repository URL. This metadata is packaged into the evidence object with `verified: true` and embedded into the HTML. The test suite later extracts this data in `archify/bin/archify.mjs` and asserts the presence of valid Git metadata, ensuring the diagram was generated from a tracked repository state.

### Can Archify link to Git hosting platforms other than GitHub?

Yes. While the examples show GitHub URLs, Archify constructs the `href` values using the repository URL obtained from Git metadata. As long as the Git remote points to a supported platform (GitHub, GitLab, Bitbucket, or self‑hosted instances), the generated links will point to the correct blob view for that specific commit and file path.

### How does the front-end viewer consume the pinned source data?

The viewer locates the `<script id="archify-source-evidence-data">` element in the DOM, parses its JSON content, and associates the `href` values with interactive diagram nodes. When users click a node, the viewer opens the corresponding URL, navigating directly to the pinned line or range in the remote repository’s web interface.