Why a pull request needs a map
PR Lens is an open-source project that turns a pull-request change into an architecture and data-flow picture. This opening asks why that extra picture matters: what does a reviewer need to know before they can judge a list of changed files? This series follows the answer from the graph PR Lens creates to the renderer and delivery surfaces that make it useful, while keeping one boundary in view: a map can orient judgment, but it cannot perform judgment for you.
The hidden work inside a diff
A pull request normally arrives as a list of files, additions, deletions, and hunks. That format is precise, but precision is not the same as orientation. Before deciding whether a change is sound, a reviewer often has to reconstruct a second representation in their head. Which request enters first? Which service owns the state? Is a new function on the main path or only a helper? What unchanged component receives its output? Which old route disappeared, and what replaced it?
That reconstruction is difficult because a diff is organized around text, while system behavior is organized around relationships. A file may define a route, call a queue, update a database, and trigger a worker elsewhere. The relevant meaning is spread across boundaries and execution time. A reviewer who reads files in their diff order may understand every local edit and still lack a reliable picture of the change as a whole.
Consider the kind of change used in PR Lens’s reference graph. A queue route remains the entry point, but it now records information that a later sender needs. A new worker reads that queued state, looks up suppressed addresses, builds a batch payload, calls an external mail provider, and writes results back. At the same time, the old per-recipient worker and single-send function disappear. The important fact is not simply that several files were added and several were removed. The important fact is that one path through the system has been replaced by another, with a different number of external calls and a different place for filtering to occur. A file-by-file view makes the reviewer assemble that sentence manually.
PR Lens addresses that gap by drawing the change against the system around it. Its architecture view is not meant to show every directory or symbol. It selects responsibilities and connections that help answer a narrower question: what did this pull request touch, and how does that touch spread? Its data-flow view answers a different question: in what order does information move through the changed path?
The distinction matters. A map that shows only newly added boxes says little about impact, because the reader cannot see what those boxes connect to. PR Lens therefore treats unchanged neighbors as part of the explanation. A modified route can be understood in relation to the queue it still writes; a new worker can be placed beside the external service it calls; a removed path can remain visible long enough for a reviewer to see what replaced it. The picture is about change, but it needs context to make change legible.
This is why the product’s promise is not simply “generate a diagram.” The useful result is a sequence of translations: text becomes relationships, relationships become a stable visual model, and that model becomes an object a reviewer can inspect before following file links into the code. The diagram is valuable precisely because it gives the reviewer a place to begin. It does not claim that a picture can replace reading the implementation; it makes the implementation’s role in the larger change easier to locate.
PR Lens is a shared map, not a single interface
The project is easier to understand if its interfaces are treated as different ways of handling the same graph rather than as unrelated features. The graph is the common boundary. A model or coding agent can author it; the renderer can draw it; a command-line workflow can compose it into Markdown; a GitHub Action can publish the images; and a hosted canvas can present the document at full size with an interactive walkthrough.
The graph itself has a small vocabulary. Lanes represent boundaries a reader can picture, such as a browser, an application runtime, a worker tier, or an external provider. Nodes represent responsibilities inside those boundaries. Edges show directed relationships such as calls, HTTP requests, events, data movement, or dependencies. Each element can be marked as added, modified, removed, or unchanged. Those marks are not decoration: they tell the reader which parts of the map changed and which parts provide the baseline for judging the impact.
Choosing lanes by behavior rather than by folders is a crucial part of this model. A repository directory can contain a route, a data type, and a test, but those files may belong to different runtime boundaries or play different roles in the path a user cares about. Conversely, one responsibility can span several directories. A reader can reason about “the web request,” “the worker,” and “the external provider” more easily than about a row of folder names. The graph’s categories are therefore a communication choice: they compress implementation detail into boundaries that explain how the system behaves.
Two lenses then turn the same vocabulary toward different forms of understanding. Architecture puts components into a spatial system: the reader can see the blast radius and the highlighted connection that matters most. Data flow puts participants into columns and messages into an ordered sequence: the reader can watch a request, event, return value, or repeated operation happen in turn. A view can narrow the picture to a new path or a retired path, while a walkthrough can focus attention on one meaningful change at a time.
The repository’s reference graph makes this concrete with a broadcast-sending change. A queue route and its surrounding system remain visible, while a new bulk sender and payload library appear as additions. The previous per-recipient processing path is marked as removed. The data-flow view then shows the queue write, trigger, one suppression lookup, repeated batch posts, returned per-message results, and the final write-back. The example does not ask the reader to memorize a document format. It demonstrates the difference between seeing what exists and seeing what happens.
That shared document also explains why PR Lens can support several operating choices without changing its central idea. Someone who wants a hosted automatic comment can use the GitHub App. A team that wants its own model key and CI permissions can use the Action. A developer can run the CLI locally, or ask a coding agent to author and render the graph it already understands. A reader who needs a larger, navigable surface can open a canvas. In each case, the review aid begins with the same question: what system change should the reader be able to see?
The map’s promise—and its boundary
The rest of this series follows the graph through four engineering problems. First, PR Lens must obtain a useful account of the change. Its CLI compares the right commits, sends a bounded diff to a provider chosen by the user, and keeps repository-known facts such as commit identity and line counts out of the model’s control. A coding agent can take a different route and author the graph directly. In both cases, the result is an interpretation of evidence, not an oracle.
Second, the document must be coherent before anyone sees it. Strict validation checks not only whether the fields have the right shape, but whether an edge points to declared nodes, a flow uses its declared participants, a view names something that exists, and a walkthrough focuses a message on the flow it actually stages. Repository corrections then provide a durable way to rename, exclude, regroup, or relocate inferred elements without editing a generated picture that will be replaced on the next run.
Third, the renderer must preserve meaning while making the picture. It draws self-contained light and dark SVGs, animates selected relationships, and lays out cards from graph structure rather than from the order in which a model happened to write them. Stability has a direct review value: a renamed label should not cause unrelated lanes to jump, and a changed diagram should receive a new content-addressed URL instead of being hidden behind an old cached image.
Finally, the result must reach the reader without losing its context. A comment can show a scaled image and link to a larger one. An automated Action must avoid publishing an older run over a newer push and must edit only the comment it owns. A canvas can add full-size navigation and a walkthrough, but it introduces a separate service and capability boundary. These are not publishing details detached from comprehension. A stale, mismatched, or unreadable image changes what the reviewer is able to understand.
There is also a limit that the project states plainly. PR Lens is a comprehension layer, not a findings engine. It has no security lens and no field for bugs, risks, or style notes. A visually coherent graph can still omit a dependency, misunderstand a responsibility, or leave an important semantic question unresolved. The reviewer must still inspect the code, test the claimed behavior, and perform the correctness and security analysis that a diagram is not designed to provide.
That separation is useful even when the graph is accurate. Structural checks can establish that the edges in a document refer to real nodes and that a flow’s messages are internally consistent. They cannot establish that the model noticed a dependency that never appeared clearly in the diff, or that the chosen lane is the best explanation for a new team member. The project’s corrections let a repository repair recurring names and boundaries, but they do not turn a generated interpretation into a canonical architecture database. Reliability here means that the artifact is coherent about what it says, not that it says everything worth knowing.
The practical standard is therefore modest but valuable: before asking whether a change is correct, make it easier to see where it lives, what it touches, and how its behavior travels. The next question follows directly from that standard. What must a single graph document preserve so the same change can be understood as a system, as a sequence, and as a focused path through a review?