Architecture, sequence or data-flow diagram: which one explains a code change?

Use an architecture diagram when the question is what the change can break, and a sequence diagram when the question is what now happens in what order. Those are the only two questions a reviewer has in the first two minutes, and GitHub's own guidance on reviewing agent pull requests gives them exactly that long to scan a change before deciding how to spend the rest. A classic data-flow diagram answers neither, for a reason worth knowing about. Most tools offering you a "data flow" of a code change are drawing a sequence and using the older name.

What each of the three actually is

An architecture diagram shows structure. Components, and which of them talk to which. A widely used vocabulary for this is Simon Brown's C4 model, which describes itself as an easy to learn, developer friendly approach to software architecture diagramming and stacks four levels: a system context diagram at the top, then containers, then components, then code. C4 is worth reading for the discipline more than for the notation. It tells you to pick a level and stay on it, and it is blunt that you rarely need all four: the site recommends system context and container diagrams for every team, and says to draw component diagrams only if they add value. A diagram that mixes a deployment target with a private helper function is one nobody can read.

A sequence diagram shows time. It comes from UML, whose current specification is version 2.5.1 from December 2017, and it draws participants as columns with lifelines dropping from them, messages as arrows between those lifelines, and activation bars where a participant is busy. The specification puts the axis plainly: each vertical line describes the time-line for a process, where time increases down the page. Everything else in the notation exists to make that ordering unambiguous. The spec is also clear about what a sequence diagram is not for, saying that interactions do not focus on the manipulation of data even though data can be used to decorate the diagrams.

A data-flow diagram, in the sense the term was coined, is a third thing. It comes out of structured analysis in the 1970s, developed and popularised by Larry Constantine, Ed Yourdon, Tom DeMarco, Chris Gane and Trish Sarson, and it draws processes, data stores, external entities and the flows between them. What it does not draw is order. The Wikipedia article on it puts the constraint plainly: a data-flow diagram has no control flow, there are no decision rules and no loops. That was deliberate, because the point was to model what a system does with data independently of how it sequences the work.

Which is why the name has drifted. When a modern tool offers to draw the "data flow" of a pull request, it almost always means an ordered sequence, because ordering is the thing a reviewer wants. PR Lens does this too. Its second lens is called data flow and it renders as a sequence: participant columns, lifelines, activation bars, return arrows and self-messages. I would rather say so plainly than pretend the name is precise.

Which question each one answers

Pick architecture when you are worried about blast radius, and a sequence when you are worried about order.

That is the whole decision in one line, but the questions underneath it are worth spelling out, because you can usually tell which you have by reading the pull request title.

An architecture diagram answers: what does this touch, what sits next to what it touched, and what did it delete. It is the right picture for a refactor, a new service, a dependency change, a deletion, or any change where you suspect something downstream is about to be surprised. It is also the right picture when you do not yet know what the change is, which is most of the time, because structure is the cheapest thing to take in.

A sequence diagram answers: what happens first, what waits for what, and how many times. It earns its place when a change altered an order of operations. Work moving behind a queue, calls that used to be made one at a time now being batched, a retry inserted, a synchronous call becoming fire and forget. On the render at the top of this post the whole point is countable: one call per batch of 500 messages, four times, where there used to be one call per recipient.

If a change did not move anything in time, a sequence diagram of it is a picture of the code you could have read from the file. Skip it.

Most changes need one picture

The temptation with two lenses is to always ship both. Resist it. A pull request that adds a config flag and a pull request that reorders a payment pipeline do not deserve the same amount of paper.

The rule I hold to is that a second diagram has to answer a question the first one raised. The architecture render shows a new queue between the route and the worker. Fine, so what does that do to the order of a request? Now the sequence earns its place. If you cannot state the question the second picture answers, it is decoration, and decoration in a pull request costs a reviewer the time they spend deciding it was decoration.

The size ladder matters here too. A one-lane, one-component change says everything it has to say in a single card, and adding a sequence to it is noise. A monorepo refactor across six lanes may need both plus a drill-down. I put all three sizes side by side in one renderer, three sizes.

What we ship, and the two places we bend the notation

PR Lens has two lenses and no plans for a third.

The architecture lens draws lanes of cards. Lanes are the reader's mental model, a runtime or a tier or a boundary, so a real diagram has lanes called things like "Next.js", "Cloud Functions" and "External" rather than src, lib and test. Every card carries what the change did to it: green for added, amber for modified, red and struck through for removed, and plain for unchanged. Keeping the unchanged ones on the page is the point, and it is the argument in blast radius diagrams.

The data-flow lens draws the sequence, and animates it. Steps share one cycle and take it in turn, one dot crossing one arrow at a time, in the order the steps happen, so the next arrow lights as the last dot lands. A step marked as repeating takes consecutive turns.

Two deviations from strict UML are worth naming, because someone will notice them.

The first is arrowheads. UML 2 draws a reply with an open head, the same head it uses for an asynchronous signal. We draw replies with a filled head and let the dashed stroke carry the whole meaning of "this is an answer", which keeps the open head as the exclusive mark of "nobody waits on this". One signal, one meaning, no legend.

The second is the message vocabulary. There are four kinds and no more: sync, async, return, and self for a step that never leaves its participant. A flow takes between two and twelve participants and between one and sixty-four steps, and a step may carry a repeat count, which is how "four batched requests" is one arrow rather than four.

How to choose in ten seconds

Two things to keep in mind whichever you pick. Neither type is any good if the diagram only contains the parts that changed, which is the failure mode of generating a picture from a diff alone: see how to generate an architecture diagram from a git diff. And neither type is any good if the layout moves between two pushes, because a reader who learned the picture yesterday has to learn it again today, which is one of the reasons Mermaid is the wrong tool for code review even though it draws these kinds of diagram perfectly well for documentation.

If you are choosing between routes rather than between diagram types, how to visualise a pull request as a diagram ranks the five that work.