# Archify Utilities for Repository Evidence and Location: Complete Developer Guide

> Discover Archify utilities for repository evidence and location within the archify/scripts package. Learn about evidence extraction, serialization, validation, and update verification for your tt-a1i/archify repository.

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

---

**The Archify utilities for repository evidence and location are located in the `archify/scripts` package, where four specialized modules handle evidence extraction, serialization, validation, and update verification.**

The `tt-a1i/archify` repository provides a toolchain that embeds verifiable source code metadata directly into generated diagrams. These **Archify utilities for repository evidence and location** capture exact repository URLs, revision hashes, file paths, and line numbers, then surface this data as interactive beacons within SVG visualizations.

## Core Evidence Utilities in `archify/scripts`

The repository evidence system relies on four primary modules that manage the entire lifecycle of source attribution, from initial capture to final rendering.

### `check-render-output.mjs` – Evidence Extraction and Beacon Rendering

Located at [`archify/scripts/check-render-output.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/scripts/check-render-output.mjs), this utility runs both server-side and client-side. After diagram rendering completes, it extracts the JSON block `archify-source-evidence-data` to verify repository URLs, revision identifiers, and line references. It then injects visual beacons using the `data-source-evidence-beacon` attribute into the generated SVG elements, enabling users to trace diagram nodes back to specific source code locations.

### `render-examples.mjs` – Evidence Serialization

The [`archify/scripts/render-examples.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/scripts/render-examples.mjs) module serializes example diagrams alongside their source-evidence metadata. It generates a hidden `<script id="archify-source-evidence-data">` element containing the repository location payload, injecting it into the HTML document so downstream renderers can consume the evidence data.

### `generate-validators.mjs` – Schema Validation Generation

Found at [`archify/scripts/generate-validators.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/scripts/generate-validators.mjs), this utility generates runtime validation code that enforces the shape of evidence payloads. It validates required fields including repository URL, revision strings, file paths, and line numbers, ensuring that only properly structured evidence enters the rendering pipeline.

### `check-update.mjs` – Update Verification

The [`archify/scripts/check-update.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/scripts/check-update.mjs) script prevents evidence drift during diagram updates. Before publishing new renders, it verifies that the diagram still points to the identical repository revision using the same evidence helpers, maintaining consistency between visual documentation and actual source code states.

## Repository Evidence Workflow Implementation

The Archify utilities for repository evidence and location operate through a three-phase pipeline that bridges server-side generation with client-side interaction.

### Server-Side Evidence Emission

The `render-examples.mjs` module constructs a structured evidence payload conforming to `schemaVersion: 1`, embedding repository metadata directly into the HTML output:

```javascript
// archify/scripts/render-examples.mjs
const evidence = {
  schemaVersion: 1,
  verified: true,
  repository: {
    url: "https://github.com/example/repo",
    revision: "a1b2c3d4",
    shortRevision: "a1b2c3d"
  },
  referenceCount: 12,
  nodes: { /* file/path/line mappings */ }
};
document.body.insertAdjacentHTML(
  "beforeend",
  `<script id="archify-source-evidence-data" type="application/json">`+
  JSON.stringify(evidence)+
  `</script>`
);

```

### Client-Side Evidence Consumption

When the page loads in the browser, the client-side portion of `check-render-output.mjs` reads the embedded evidence block and decorates diagram elements with traceability attributes:

```javascript
// archify/scripts/check-render-output.mjs – browser execution context
const evidenceEl = document.getElementById('archify-source-evidence-data');
if (evidenceEl) {
  const evidence = JSON.parse(evidenceEl.textContent);
  evidence.nodes.forEach(node => {
    const el = document.querySelector(`[data-node-id="${node.id}"]`);
    if (el) {
      el.setAttribute('data-source-evidence-beacon', '');
      el.setAttribute('data-source-evidence-count', String(node.references));
    }
  });
}

```

### Validation Before Publishing

The `check-update.mjs` utility imports validators from `generate-validators.mjs` to gate the publication pipeline:

```javascript
// archify/scripts/check-update.mjs
import { validateEvidence } from "./generate-validators.mjs";

const newEvidence = /* extracted from new diagram */;
if (!validateEvidence(newEvidence)) {
  throw new Error("Invalid repository evidence – aborting update");
}

```

## HTML Template Integration

The evidence workflow is orchestrated by HTML templates located at [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) and [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html). These templates include the `<script id="archify-source-evidence-data">` placeholder element that holds the repository evidence payload. When the documentation site loads, the templates automatically invoke `check-render-output.mjs` to process the embedded JSON and activate the visual evidence cues on the rendered diagrams.

## Summary

- **The `archify/scripts` package** contains all utilities for handling repository evidence and location data in the Archify toolchain.
- **`check-render-output.mjs`** extracts evidence JSON and renders visual beacons that map diagram elements to source code lines.
- **`render-examples.mjs`** generates the hidden evidence payload embedded in every diagram page.
- **`generate-validators.mjs`** creates runtime validators ensuring evidence schema compliance for repository URLs, revisions, and line references.
- **`check-update.mjs`** verifies evidence consistency before allowing diagram updates to publish.
- **HTML templates** in `scripts/` provide the integration points that load these utilities and embed the evidence data structure.

## Frequently Asked Questions

### Where exactly are the Archify utilities for repository evidence stored?

According to the `tt-a1i/archify` source code, the utilities reside in the `archify/scripts` directory. The four main files are `check-render-output.mjs`, `render-examples.mjs`, `generate-validators.mjs`, and `check-update.mjs`, which together handle evidence extraction, serialization, validation, and update verification.

### How does `check-render-output.mjs` validate repository locations?

This utility extracts the `archify-source-evidence-data` JSON block from the rendered HTML and verifies that the `repository.url` and `repository.revision` fields match expected formats. It confirms that line references in the `nodes` object correspond to actual file paths before adding the `data-source-evidence-beacon` attributes to SVG elements.

### What schema does the repository evidence payload follow?

The evidence payload uses `schemaVersion: 1` and requires a `repository` object containing `url`, `revision`, and `shortRevision` strings, plus a `nodes` collection that maps diagram elements to specific file paths and line numbers. The `generate-validators.mjs` module enforces this schema at runtime to prevent malformed evidence from entering the rendering pipeline.

### How does Archify ensure evidence consistency across diagram updates?

The `check-update.mjs` script runs before publishing any diagram update, using validators imported from `generate-validators.mjs` to compare the new evidence payload against the previous version. It specifically checks that the `repository.revision` remains consistent, throwing an error and aborting the update if the evidence references have changed or become invalid.