Use case

Preparing an architecture review.

Most of the effort in an architecture review goes into producing the diagrams, and most of those diagrams describe the system as remembered rather than as built.

Download for macOS
v0.1.33 · .dmg · Apple Silicon & Intel
Signed & notarized by Apple · opens without a Gatekeeper warning
sha256 698955a0187bc039f4c74f5d05a9f10fbb27376a45788a0a241d1326b73873c7
Download for Windows instead
$curl -fsSL https://lucidtrain.com/install.sh | sh
Payment system architecture. 12 components across 5 tiers.
Payment system architecture. Produced by the app's layout engine from a semantic graph, not placed by hand.

The situation

A review is scheduled and someone spends two days making diagrams. Those diagrams are drawn from memory and from the last set, which were also drawn from memory, so the review is conducted against a description that has been drifting from the system for some time. The discussion is then about the description.

Generate from the system

Generating from the repository and the infrastructure code means the review starts from what is deployed. The corrections people make during the review are then real findings rather than fixes to your drawing, which changes what the meeting is for.

Several views, not one

A review usually wants four: context so everyone agrees on the boundary, containers so the pieces are named, data flow for the request that matters, and failure so the single points are explicit. Trying to serve all four with one diagram is why review decks are unreadable, and generating them separately costs little.

The failure view earns the most

The single-points-of-failure diagram is the one that produces action items, and it is the one least often prepared because it is the most tedious to draw by hand. Marking components whose loss takes the system down is a small annotation and it reliably starts the most useful conversation in the room.

The four views

shell
# Draw the context diagram: system boundary, users, external systems.
# Then containers, then the data flow for a checkout, then mark the single
# points of failure.
FAQ

Questions

Will reviewers trust a generated diagram?

More than a hand-drawn one, in practice, once they know it came from the code. The usual reaction is to start correcting it, which is exactly what you want a review to do.

What if the generated diagram is wrong?

Then you have found a gap between the code and your understanding before the review rather than during it, which is the cheaper time to find it.

Can it produce a deck?

It produces diagrams; the deck is yours. Exporting SVG means they scale cleanly in whatever tool you present with.

Related