How Repository Evidence Works in Architecture Diagrams

Archify embeds cryptographically verified source code links into architecture diagrams by validating local Git repositories against declared GitHub URLs and 40-character commit SHAs, ensuring every visual node maps to an immutable, exact line of code.

Repository evidence transforms static architecture diagrams into interactive, source-verified documentation within the Archify ecosystem. By pinning visual components to specific Git commits and file paths, the system creates an unbreakable chain between high-level design and implementation details. This feature operates entirely within the architecture diagram type and requires explicit opt-in through JSON metadata and CLI flags according to the tt-a1i/archify source code.

Declaring Repository Evidence in Diagram JSON

To enable verification, the diagram must declare repository metadata at the top level and attach source references to individual components.

The meta.repository Object

The diagram JSON requires a meta.repository object containing a public GitHub URL and a full 40-character commit SHA. This declaration signals Archify to activate the verification pipeline defined in archify/renderers/shared/repository-evidence.mjs.

{
  "type": "architecture",
  "meta": {
    "repository": {
      "url": "https://github.com/example/project",
      "revision": "9f1a1cf1afdc04d7b5406782b40dfec76d9bc798"
    }
  }
}

Component Source Entries

Individual components list their evidence in a sources array. Each entry specifies a relative file path and optional line range. The verifiedSourcePath function validates these entries for POSIX compliance and path safety.

{
  "components": [
    {
      "id": "router",
      "label": "API Router",
      "sources": [
        {
          "path": "src/router.js",
          "line": 42,
          "end_line": 58,
          "label": "Router entry point"
        }
      ]
    }
  ]
}

The Repository Evidence Verification Pipeline

When the user invokes the renderer with --repo-root, Archify executes a multi-stage validation pipeline to ensure the local repository state matches the authored metadata exactly.

Architecture-Only Restriction

Repository evidence is strictly limited to diagrams of type architecture. The hasRepositoryEvidence function checks the diagram type at lines 81-86 of repository-evidence.mjs and aborts with a diagnostic error if evidence is present in any other diagram type.

CLI Flag and Local Repository Binding

The --repo-root <path> flag is mandatory when repository evidence is declared. The verifyRepositoryEvidence function (lines 114-119) uses this path to locate the local checkout that corresponds to the authored repository metadata.

archify render diagram.json --repo-root /path/to/project --mode architecture

Git Remote and Revision Verification

Using internal helpers runGit and gitValue (lines 20-38), Archify performs three critical validations:

1. Resolves the repository top-level directory
2. Verifies the origin remote matches meta.repository.url
3. Confirms the declared commit SHA exists in the local Git history

Source Path Syntax Validation

The verifiedSourcePath function (lines 47-64) enforces strict POSIX-style relative path constraints:

• No leading slashes or backslashes
• No empty segments, ., .., or .git components
• Valid line range syntax where end_line ≥ line

Blob and Line Count Verification

For each source entry, Archify executes git cat-file -t to verify the object is a blob (file) rather than a tree or commit. When line numbers are specified, the system runs git show to fetch content and validate that the requested line range exists within the file boundaries (lines 86-100).

Generating Verified Evidence in the Output

Successfully verified sources are transformed into Semantic Passport entries. The rendered HTML includes a source-evidence beacon—a small clickable icon on the visual node that expands to reveal a verified GitHub URL:

https://github.com/<owner>/<repo>/blob/<sha>/<path>#L<line>-L<end>

This link points directly to the exact code lines, pinned to the immutable commit SHA declared in the diagram metadata.

Error Handling and Diagnostic Guidance

When any verification check fails, the evidenceFailure function (lines 9-18) throws structured diagnostic errors containing:

• A machine-readable code for automated processing
• A human-readable message explaining the failure
• A list of supportedFixes (e.g., "install Git", "use a repository-relative path", "pin a full commit SHA")

This structured error format guides diagram authors to correct metadata issues before the final HTML artifact is generated, preventing broken or unverified links from appearing in published documentation.

Summary

• Repository evidence requires the architecture diagram type and explicit --repo-root CLI flag to activate the verification pipeline.
• The meta.repository object must contain a valid GitHub URL and full 40-character commit SHA.
• Local Git validation occurs through runGit and gitValue helpers, verifying remotes, revisions, and object types before rendering.
• Source paths undergo strict POSIX validation via verifiedSourcePath to prevent directory traversal and ensure cross-platform compatibility.
• Verified evidence renders as clickable source-evidence beacons linking to immutable GitHub blob URLs with line anchors.
• All failures route through evidenceFailure, providing structured diagnostics with supportedFixes for rapid remediation.

Frequently Asked Questions

Can I use repository evidence with sequence or flow diagrams?

No, repository evidence is restricted to architecture type diagrams only. The hasRepositoryEvidence function in archify/renderers/shared/repository-evidence.mjs explicitly checks the diagram type and aborts if evidence is present in other formats, maintaining a strict separation between architectural views and behavioral diagrams.

What happens if my local repository is on a different commit than declared?

Archify validates the commit SHA against the local Git history using gitValue commands. If the revision is missing or the origin remote URL mismatches the meta.repository.url, evidenceFailure emits a diagnostic error suggesting you fetch the remote, checkout the correct commit, or correct the repository path in your diagram JSON.

Are absolute paths or parent directory references allowed in source entries?

No, the verifiedSourcePath function explicitly rejects paths containing leading slashes, backslashes, ., or .. segments to prevent directory traversal attacks. All source paths must be relative POSIX paths without empty segments or .git components, ensuring the diagram remains portable and secure.

Is the --repo-root flag optional when repository metadata is present?

No, the --repo-root flag is mandatory when repository evidence is declared. Without it, verifyRepositoryEvidence cannot locate the local checkout to perform Git validation, and the renderer will abort with a diagnostic error before generating any HTML output.

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