Archify Repository Evidence for Architecture Nodes: Understanding the SRC Marker System

Archify uses a viewer-only SRC marker to link architecture diagram nodes directly to verified source code lines in public Git commits, ensuring reproducible traceability without cluttering exported artifacts.

Archify is a Node.js-based rendering and validation platform that transforms textual descriptions or repository code into deterministic, interactive system maps. The architecture node evidence feature creates an auditable trail from every diagram element back to its implementation, using a lightweight validation system that confirms every reference against actual Git history. This evidence-backed approach guarantees that stakeholders can verify architectural claims against canonical source code.

How the SRC Source-Beacon System Works

The core of Archify’s evidence system is the SRC marker, a viewer-only badge that appears on nodes with validated source attributions.

Typed JSON IR and Source Attribution

Agents generate a deterministic JSON representation of the architecture where each node can optionally include a source field. This field contains:

• repo: The HTTPS URL of the public Git repository
• commit: The exact SHA hash to reference
• file: The relative file path within the repository
• range: The specific line numbers (e.g., "15-27")

Only nodes containing this complete source block are candidates for evidence-backed rendering.

The Validation Pipeline

Before a node receives the SRC marker, Archify’s bundled validators perform strict verification. In archify/bin/archify.mjs, the validate command confirms that the referenced commit exists in the repository and that the specified file and line range are reachable. The node is marked as evidence-backed only after passing all schema, layout, and source-verification checks.

SRC Marker Implementation

When the browser-based viewer renders the diagram, evidence-backed nodes receive a small "SRC n" capsule in the upper-right corner. This marker is defined in archify/renderers/shared/i18n.mjs, where the token viewer.passport.sourceMarker is set to ['SRC', '来源'] at line 388. The numeric identifier maps to a semantic passport that records the node’s provenance, and the badge is fully accessible to screen readers.

Creating Evidence-Backed Architecture Diagrams

You can generate diagrams with source evidence using the Archify CLI or programmatic API.

CLI Workflow

First, create a Typed JSON IR file that includes the source attribution:

cat > example.json <<'EOF'
{
  "nodes": [
    {
      "id": "api",
      "label": "API Server",
      "kind": "backend",
      "source": {
        "repo": "https://github.com/example/project",
        "commit": "a1b2c3d",
        "file": "src/api/server.js",
        "range": "15-27"
      }
    }
  ],
  "edges": []
}
EOF

Validate the IR to ensure the source exists:

node archify/bin/archify.mjs validate architecture example.json --json

Generate the self-contained HTML artifact:

node archify/bin/archify.mjs deliver architecture example.json api-diagram.html --open

The resulting HTML contains the SRC badge that appears only in the interactive viewer.

Programmatic Generation

For dynamic generation within Node.js applications:

import { render } from '@tt-a1i/archify';
import fs from 'fs';

const ir = JSON.parse(fs.readFileSync('example.json'));
const html = await render('architecture', ir, { 
  meta: { visual_preset: 'signal-flow' }
});
fs.writeFileSync('api-diagram.html', html);

The source block in the IR causes the viewer to display the SRC 1 badge on the corresponding node.

Viewer Interaction and Export Behavior

The SRC system is deliberately lightweight and non-intrusive. When you open api-diagram.html in a browser and hover over a source-backed node, the SRC n badge renders in the upper-right corner. Clicking this badge opens a read-only modal view anchored to the exact file, line range, and commit SHA, guaranteeing reproducibility.

However, the marker is viewer-only by design. As documented in DESIGN.md, the SRC capsule is stripped from all canonical exports including PNG, SVG, and WebM files. This ensures that shared artifacts remain clean and layout-stable while preserving on-demand traceability for interactive users. The viewer logic handling these interactions resides in viewer/viewer-chrome-layout.js.

Summary

• SRC markers link architecture nodes to verified source lines without affecting diagram layout
• Validation pipeline in archify/bin/archify.mijs confirms commit existence and file reachability before marking nodes as evidence-backed
• Typed JSON IR provides the deterministic format where the source field attaches repository evidence to nodes
• Viewer-only rendering keeps the badge interactive and accessible while excluding it from static exports
• Internationalization support includes both English ("SRC") and Chinese ("来源") labels defined in archify/renderers/shared/i18n.mjs

Frequently Asked Questions

What file contains the SRC marker definition in Archify?

The marker definition lives in archify/renderers/shared/i18n.mjs at line 388, where the token viewer.passport.sourceMarker is set to the array ['SRC', '来源']. This file manages internationalization strings for the viewer interface.

Does the SRC marker appear in exported diagrams?

No. The SRC marker is deliberately stripped from all exports including PNG, SVG, and WebM formats. It appears only in the interactive browser-based viewer, ensuring that shared artifacts remain clean while maintaining source traceability for interactive users.

How does Archify validate repository evidence for architecture nodes?

Archify runs a validation pipeline that confirms the referenced commit exists in the public repository and verifies that the specified file path and line range are reachable. This validation occurs in the CLI via archify/bin/archify.mjs and must succeed before a node is marked as evidence-backed.

Can I programmatically generate diagrams with source evidence using the Archify API?

Yes. Using the @tt-a1i/archify package, you can pass a JSON IR containing source objects to the render() function. The resulting HTML string will include the necessary metadata to display SRC markers when viewed in a browser.

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