Architecture diagrams are persuasive. A line from a route to a handler looks like a fact even if someone drew it from memory six months ago. A tool that generates the line has the same responsibility: show where it came from, or make the gap visible.

That principle shapes CARTOGRAPH, a local tool for scanning supported TypeScript projects, producing a deterministic architecture graph, and comparing two Git revisions. Every emitted relationship carries repository-relative source evidence—or an explicit reason it could not be resolved.

Three states for an architecture edge A verified relationship with source evidence, an unresolved relationship with a reason, and an unsupported construct retained as a diagnostic. route → handlerVERIFIED · source: routes.ts:18 module → targetUNRESOLVED · dynamic import DIAGNOSTIC · no guessed edge edge + evidencereason, no edgeuncertainty kept
Resolved, unresolved, and unsupported should remain different states.

Static analysis has an edge

No analyzer sees every runtime path. Dynamic imports, reflective calls, framework conventions, and generated code can all hide relationships from a static pass. There are two tempting mistakes: silently omit the relationship, or infer a plausible edge and make the graph look complete.

Both choices erase useful information. Omission looks like absence. A guess looks like knowledge. CARTOGRAPH keeps unresolved constructs visible as diagnostics instead. The output can say what the analyzer understood, which evidence supports it, and where its current model stops.

Diff the shape, not just the files

A revision diff can show that files changed; an architecture diff asks what those edits did to the relationships the tool can model. CARTOGRAPH compares two Git revisions and reports added, removed, or changed graph nodes and edges. Deterministic output makes the same source state produce the same snapshot, which gives the diff a stable basis for review.

That is still a structural view, not a complete account of runtime behavior. The graph does not execute the repository. The supported slice is explicit, and unsupported constructs remain visible rather than being presented as covered.

Current boundary: CARTOGRAPH is pre-alpha. Its local TypeScript/Express slice and bounded adapters are implemented; stable identity across refactors and broader framework coverage remain open work. The project page lists the support table and limitations.

“Unknown” is a useful result

I want architecture tools to help people ask better questions, not replace judgment with a polished picture. An evidence-backed edge can be inspected. An unresolved edge can be investigated. A guessed edge can quietly become part of someone’s mental model.

For this kind of tool, “I don’t know yet” is not a broken report. It is part of the report—and often the most useful thing in it.