Use Git Diffs to Make Architecture Changes Easier to Review

Reviewing a pull request that changes several services can be difficult even when the code is clear. The diff may show a new client, a storage adapter, or a queue consumer across dozens of files, while the architectural consequence is one sentence: a new dependency now crosses a boundary.

Architecture diagrams can make that consequence easier to discuss, provided they stay focused. The goal is not to replace line-by-line code review with a picture. It is to give reviewers a second view of the change at the level where design decisions are made.

Why code diffs can hide system impact

Git compares file content. It does not inherently know that one package represents a subsystem, that two names refer to the same service, or that a new call changes an important trust boundary. Those meanings come from a model or from human interpretation. Large diffs can also scatter one architectural change across migrations, configuration, handlers, and tests.

A diagram adds useful context by making relationships spatial. It can show a changed element alongside direct neighbors, so a reviewer can ask whether the dependency is expected and whether the direction makes sense. A good impact view answers “what around the change should I inspect?” It does not claim that every runtime behavior is represented.

Start with a narrow question

Before generating or editing a diagram, state what the review is about. Is a new service being introduced? Is a database shared across boundaries? Did a synchronous call become asynchronous? Does a deployment change add a dependency on an external provider? A narrow question prevents the diagram from becoming another copy of the entire repository.

Then choose the smallest useful context. Show the changed element and enough surrounding relationships to make the design legible. If the decision depends on an internal flow, link or drill into a more detailed view rather than crowding the overview with every module.

Compare revisions with tl;diagram

The open-source tld CLI includes tld git compare for comparing two Git revisions, such as adjacent commits or a main branch and a feature branch. The documented default output is a JSON impact scene. It tries to match changes to authored diagrams where possible and can fall back to mapped or file elements. A changed-file ledger provides another path back to the source diff.

A simple local comparison looks like this:

tld git compare HEAD~1 HEAD

You can compare named branches, commits, or tags, and request Mermaid output when a text diagram is more useful:

tld git compare main feature-branch --mermaid

The --blast-radius option adds zero to two dependency hops around the changes; zero is the default. Increase it when a direct change is too isolated to explain, then reduce it if the result becomes noisy. The command also provides options to restrict comparison to a view, export Mermaid or Markdown, write a JSON report, and set output budgets. Check tld git compare --help for flags in your installed version.

Make the result useful in a pull request

1. Keep the code diff primary. A diagram is additional context; reviewers still need to inspect implementation, tests, and configuration.
2. Call out the decision. In the pull request description, explain why a new relationship exists, what alternatives were considered, and whether the architecture model changed.
3. Inspect provenance and omissions. A mapped source element is not the same thing as a deliberately authored architecture component. Confirm that the output represents the behavior relevant to the decision.
4. Limit the scope. Use a focused view or smaller dependency radius when the full system obscures the change.
5. Keep artifacts shareable with care. If you create a self-contained URL output, remember the documentation says anyone with the link can read the embedded scene. It does not upload the scene for you.

Where automation helps, and where it stops

Running comparison as part of a review process can make architectural changes easier to spot. The project documents a PR diagram bot that can post diagrams on pull requests. Automation is best at surfacing a view consistently; it cannot decide whether an architectural move is desirable. A human reviewer still needs to understand the design intent and validate the code against it.

There are also limits to source-based evidence. Indexing depends on supported languages and available source information, and generated files or dynamic runtime behavior may not tell the whole story. Treat a comparison as a navigation aid. If the architecture diagram has not been maintained, the missing context is itself a review finding worth addressing.

See the Git comparison guide for supported options and output details, and the indexing documentation for source maps. Browse the implementation and issue tracker in the open-source repository.