How Archify Pins Diagram Nodes to Git‑Verified Source Files

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

// 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 (sourced from 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:

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

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:

<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.

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