Architecture · · 7 min read
A graph should answer a code question
How to read Weavatrix evidence, full-screen code towers, and the difference between a report and a repository binding.
A graph is useful when it helps answer where a change could matter, which component owns a behavior, and what evidence supports a relation. A polished picture with unverified edges is worse than a smaller, honest report.
With the separately distributed Engine enabled, GrantTap can present Weavatrix reports for components and relations. The Health code map gives a full-screen way to inspect files and symbols. Both views need the same revision context to support a claim about the current checkout.
Read the report label first
Check the repository, engine version, source revision, scan time, and completeness. A report generated for another checkout or an old commit may still be interesting, but it is not current proof for your Task. Search and component inspection help narrow the view; a missing edge should not be interpreted as proof that no dependency exists outside the analyzed scope.
The code-towers screenshot in this article is a deterministic fixture labelled demo-revision. It shows navigation and rendering behavior, not an independent scan of a customer's private code.
Use code towers to orient, then inspect
The full-screen Health map groups code visually so you can find a file or symbol, understand its neighborhood, and open details. Tall or bright geometry is a navigation aid, not a quality score. A component deserves a stronger claim only when its underlying source and relation evidence can be inspected.
If architecture is unavailable on one computer, first check that its repository is bound and that the Engine can reach that checkout. The product should offer an explicit build or refresh action when supported. It must not claim that a connected Weavatrix library is absent merely because this chat has no current report.
From graph to action
For a coding Task, the next useful step is a revision-bound impact packet: what changed, which related components may be affected, why, and how fresh that conclusion is. The graph can supply evidence to Cortex context selection, but a stale or missing impact packet must be visible. A relation by itself does not calculate cost, authorize a command, or prove a test passed.
Ask a question before opening the graph
A large graph is tempting because it makes a repository feel comprehensible at a glance. It can also hide the question that brought you there. Start with a concrete concern: which callers depend on this contract, what might an API rename affect, or who owns the failing behavior? Then select the smallest relevant neighborhood. A graph that leads to inspectable code can help; a wall of colored nodes that cannot justify its edges mostly creates false confidence.
The answer should include a scope label. Was the entire repository analyzed, only a package, or a checked-out subset? Was generated code omitted? Did the scanner see dynamic imports or runtime configuration? Different analyses observe different relationships. A missing edge means only that this report did not show one in its covered scope. It does not prove that a dependency cannot exist through a route the analysis did not inspect.
Revision is part of every claim
Source evidence is time-bound. A report for yesterday's commit can be an excellent navigation aid, yet it cannot establish the state after today's refactor. Record the repository identity, checkout revision, engine version, report time, and completeness together. If an agent uses a relation while editing a newer checkout, it should state the mismatch and inspect current source before making a strong impact claim. This is not ceremony; it prevents an old map from becoming a new fact.
The same principle applies when several computers hold copies of a repository. A familiar branch name can point at different commits or uncommitted changes. A Project link tells you where a repository is bound, while a report tells you what one analysis observed. The receiving execution should compare its own checkout to the report's revision. If they differ, the interface should make the gap visible instead of silently painting every edge as current.
Trace the edge to something reviewable
A useful architecture relation is a path back to source: a file, symbol, declaration, or reproducible observation. Consider a diagram saying that a mobile view depends on a relay event. A reviewer needs to find the event contract and the consuming code, not simply trust the arrow. Declared relationships are valuable for design intent, but their label should remain distinct from a relationship discovered from source. Each kind answers a different question.
When evidence is incomplete, show that status at the edge. An unresolved symbol, excluded package, or unavailable checkout should not be smoothed away by visual polish. The darker parts of the generated illustration represent precisely that uncertainty; they are not a metric. For an actual Task, inspect the underlying report and source location. The goal is to shorten the route to verification, not to replace it with an attractive picture.
From orientation to impact
Once an edge is grounded, use it to plan a bounded check. If a contract changes, inspect direct consumers, then run targeted tests or build steps for the affected modules. A code map can suggest the relevant area, but it cannot decide whether a behavior is correct after the edit. A passing test also has limits: it covers the tested scenario and revision, not every possible runtime path. Keep the map, change, and verification linked to the same source state.
A future impact packet can summarize changed files, related components, source windows, and unresolved questions for a coding agent. Such a packet needs a revision and evidence trail. It should not become a claim that every dependency is known or that a model can safely skip review. GrantTap's Engine and Weavatrix path are conditional on installation and available reports; the architecture article describes how to read their output, not a universal automatic scan.
What the product screenshot actually shows
The Health code-towers capture in this article is a deterministic fixture. It demonstrates the spatial navigation interface: select an area, inspect a file or symbol, and move from broad orientation to detail. It does not represent a customer's repository or prove that the depicted relations were discovered live. The generated pictures above are even more abstract: they explain evidence-backed edges and traceability. Their captions keep these roles separate.
When using your own installation, look for the report label rather than assuming the visual shape is a quality score. A tall structure may simply represent a grouping or visual encoding; it is not a verdict on code health. If the Engine is unavailable on the target computer, the right next step is to check the binding and report status. A missing report is a state to surface, not a reason to invent one.
A practical reading sequence
Begin with the Task question and the current checkout. Open the architecture report only if its revision and scope are relevant. Select one suspected component and follow a small number of relations to their source. Compare declared links with observed ones, then run the narrowest verification that could disprove your working hypothesis. Write down what remained outside the report. This sequence is slower than trusting the whole graph instantly, but usually faster than debugging an unsupported assumption.
Finally, explain the result in ordinary language: which source supports the relation, what test or observation checked the proposed change, and what remains uncertain. That explanation is useful to another agent, a reviewer, and the person returning to the Task on a phone. The graph earns its place when it helps answer a code question with evidence that survives the next session, not when it merely looks complete.
