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

> Archify links diagram nodes to source code lines using SRC markers for reproducible traceability. Discover how Archify repository evidence works.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-09-13

---

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

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

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

```

Generate the self-contained HTML artifact:

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

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.