How to trace a diagram back to the source code that proves it
Select an imported component and read the evidence behind it: the file and line range, the commit, and a link that opens the code at that exact commit.
When this is useful
- Someone challenges a diagram and "trust me" is not a sufficient answer.
- You are reviewing an architecture and want to check a specific claim rather than all of them.
- An audit asks how architecture documentation is kept accurate.
Before you start
- An architecture imported from a document that carries source references. Evidence exists only on shapes an import created — a shape you drew yourself has none, correctly.
- The import review screen counts the evidence it found. If that count was zero, there is nothing to trace and the panel will say so.
Step 1: Select a single imported shape
Click one shape. The panel is per-element, so a multi-selection is not what it reads.
Step 2: Open the Trace tab in Properties
The Evidence section lists each record behind that component: the file and line range, how the evidence bears on the claim, the commit, a verification status and a confidence value.
Most first-pass imports read as unverified. That is the honest state, not a failure — it means nobody has confirmed the claim by hand yet.
Step 3: Open the code at the pinned commit
Where a permalink is available it opens the repository at the exact commit the evidence was captured from, scrolled to those lines.
A link is offered only when the record carries a repository, a full commit SHA and a file path, and the repository is on GitHub or GitLab. Anywhere else, no link is shown rather than a guessed one — a link to a branch tip would point at code that has since moved, which is precisely what pinning to a commit exists to prevent.
What happens next
Re-running the analysis at a later commit and re-importing refreshes the evidence, so the diagram's claims stay pinned to code that currently exists.
Example
A reviewer questioning whether a service still calls the payments API selected the connector, read `src/api/orders.ts:12-40`, opened it at the pinned commit, and closed the question in under a minute.
Tips
- Clicking a shape with no evidence shows an empty state. That is the correct answer for a hand-drawn shape — do not read it as a fault.
- If every shape shows the empty state, the imported document contained no source references. The fix is on the analysis side, not here.
Limitations
- Permalinks are built for github.com and gitlab.com only. A self-hosted repository is handled by showing no link.
- Evidence is only as current as the commit it was captured at.