The graph behind the picture
PR Lens becomes useful only when its diagram has a model underneath it. This chapter examines that model: how lanes, nodes, edges, deltas, views, flows, and walkthroughs preserve different kinds of meaning in one document. By the end, you should be able to look at a PR Lens picture and tell whether it is showing where a change lives, what it does in sequence, or simply what the reader has been asked to notice first.
A graph follows responsibility, not file order
A PR Lens graph is a compact description of a system change. It carries the repository and commit context that the picture came from, a title and summary, the lenses it can support, and the elements that make the system legible. The important elements are not files arranged in a directory tree. They are responsibilities arranged around the boundaries through which behavior passes.
A lane is one of those boundaries. It might represent a web application, a worker runtime, a data store, or an outside service. The choice is meant to match a reader’s mental model of the system. “Web request,” “background worker,” and “mail provider” usually say more about a change than three folder names. One responsibility may draw from several directories, while one directory may contain code that belongs to several runtime roles. Treating folders as architecture would preserve the repository’s filing system but lose the system’s behavior.
A node is a responsibility inside a lane. Its label should tell the reader what the part does; its subtitle or file reference can preserve the name a developer will recognize. The node’s kind—such as route, function, queue, datastore, or external service—controls its icon and shape. It does not claim that a function is more important than a queue, or that a particular kind has a fixed runtime meaning. It is a visual aid for recognition.
An edge is a directed relationship between two nodes. It can represent a call, an HTTP request, an event, a queue hand-off, data movement, or a dependency. Direction matters because the reviewer is trying to understand what crosses a boundary and what triggers the next transition. A small number of edges can be emphasized as the connection the change is really about. If everything is a hero connection, nothing guides the eye.
This compression has a useful limit. A node is not a claim that one file, class, or function owns an entire behavior, and a lane is not a claim that every item in a directory runs in the same place. The graph keeps file references so a reviewer can move from a responsibility to source evidence, but it does not let those references dictate the explanation. That is why the model can be simpler than the repository without being arbitrary: it is organized around the question the reviewer needs answered.
Every node and edge also carries a delta: added, modified, removed, or unchanged. This is the graph’s most direct answer to “what changed?” A new worker can be green, a changed queue amber, and a retired path red and ghosted. But the fourth state is just as important. An unchanged route or provider can explain the location and reach of the change. Without those neighbors, the map becomes a collection of colored additions with no baseline.
The reference graph for PR Lens’s batch-broadcast example shows why these parts belong together. The queue route remains in the web lane and the external mail provider remains at the far boundary. A new sender, payload builder, suppression lookup, and shared library appear in the worker lane. The previous per-recipient processor and single-send function remain visible as removed elements. The edges make the replacement explicit: the queue now triggers the bulk sender, and the bulk sender reaches the provider through a batch request rather than one request per recipient.
That example is not just a prettier file list. It encodes a claim about system behavior: one path has been replaced by another. The nodes identify the responsibilities that participate, the lanes identify the boundaries they cross, and the deltas identify the parts of the transition. A reviewer can then ask a more useful question than “what files are new?” They can ask whether the new path owns the same state, reaches the same external boundary, and retires every old route that should no longer run.
The graph’s other fields support that reading without changing its center. File references can lead to the relevant lines at the base or head commit. A summary can explain a node or edge when a label is too small to carry the whole meaning. Statistics and headline chips can make a scale change visible. Optional layout hints can express an intended lane order or preferred depth, while the renderer remains responsible for final placement. These details serve the map; they do not replace it.
Two lenses, one path
The same graph can answer two different questions. The architecture lens shows the affected system and its blast radius. It is spatial: lanes stand beside one another, cards occupy positions, and edges show relationships around the change. This is the lens to use when a reviewer needs to locate a new component, see what remains connected, or understand what was removed.
The data-flow lens shows an ordered pipeline. Its participants become columns, and its messages become steps between them. A message can be synchronous, asynchronous, a return, or a self-message. The array order is the sequence; there is no separate step number that could disagree with the animation. A repeated message can express a repeated operation, such as four batch requests in a sample broadcast. The visual movement is therefore tied to behavior: it shows not only that two components are related, but when one hands work to the other and what comes back.
The message kinds also preserve a small amount of control meaning. A synchronous call implies that the receiver is working on behalf of the sender until a matching return; an asynchronous hand-off does not imply that the sender waits; a return carries an answer back; and a self-message keeps work inside one participant. Those distinctions keep the sequence from becoming a row of generic arrows. They tell the reader whether the next moment is a response, a queued transition, or internal work that never crosses a boundary.
Architecture and data flow are deliberately not two zoom levels of one picture. A narrower architecture view can show the new path without the rest of the system. A flow view can show the sequence of that path without pretending that temporal order is a spatial dependency map. Trying to make one diagram serve both purposes usually produces either a crowded architecture picture or a sequence that hides the system boundary it crosses.
A view gives the document a way to make that distinction navigable. A whole view can show the blast radius. A child view can select the new path or the retired path and leave unrelated elements out. A selection does not mean “draw only these ids no matter what.” If it selects an edge, the renderer brings along both endpoints; if it selects a node, it can bring along the lane that holds it. The rule is practical: an arrow that ends in empty space is worse than an omitted arrow. A selected view should be narrower, but it must still be intelligible.
Views form a drill-down tree that a comment can render as nested details. The top architecture view can be open by default, while narrower sections remain available for a reader who wants to inspect one responsibility. Data-flow views stay as separate roots because a sequence is a different explanatory object. The graph does not change when a reader opens a child view. Only the scope of the picture changes.
A walkthrough adds a reading order on top of those scopes. It is a short set of steps, each with a heading, one line about what the change means, an optional stage naming a view or flow, and a focus naming the lanes, nodes, edges, or messages that should remain lit. The purpose is not to describe the diagram in general. It is to say, for example, that the sender now works on a whole batch, then point at the batch request and its results, then return to the full blast radius. When the reader moves to the next step, the surrounding picture can dim while the relevant relationship stays visible.
The walkthrough is therefore a third kind of meaning. Architecture says what is connected. Data flow says what happens in order. The walkthrough says what deserves attention at this moment. It does not create a new graph for each sentence. It points into the existing one by id, which is why the contract can check whether a step still refers to a real node or a message in the flow it stages.
This distinction also explains why a correction or exclusion must affect more than the card it names. If an excluded node leaves an edge with only one endpoint, the edge no longer explains a relationship. If it removes the last participant from a flow, the sequence no longer has a meaningful path. If a walkthrough loses the last element it focuses on, leaving the step in place would quietly turn a precise instruction into an empty caption. PR Lens narrows or removes those dependent pieces rather than widening them into a misleading picture.
One document prevents five pictures from drifting apart
The graph’s shared identity is an engineering choice, not just a convenient data format. If the architecture picture, the sequence picture, the comment text, and the hosted canvas were each generated from separate interpretations, small disagreements would be hard to detect. One surface might call a component a worker, another might omit it, and a third might animate a path that the first did not draw. A single document gives all of them the same node ids, edge endpoints, deltas, and provenance.
That shared contract also keeps the surfaces honest about what they can do. A renderer can draw only the lenses the document declares. A view can scope only elements that exist. A data-flow message must use participants in its own flow, not merely any nodes elsewhere in the document. A canvas can play a walkthrough only when its stages and focuses resolve against the diagrams it presents. These are not restrictions added after the design; they follow from the decision to let one graph carry the meaning across interfaces.
The result is a useful way to read PR Lens. Start with lanes and nodes to locate responsibility. Follow edges to understand relationships and deltas to identify the transition. Switch to a flow when sequence determines behavior. Use views and walkthrough focus to reduce the amount of the picture competing for attention. At every step, ask whether the visual element adds a fact about the system or merely adds detail.
The next problem is how this document gets filled from an actual pull request. A graph can preserve context only if the input comparison is correct, the model sees enough of the diff, and repository facts do not become guesses. The question is no longer what the graph means, but how PR Lens produces a draft without letting the draft rewrite the evidence it came from.