Use case

Planning a migration.

Migrations fail on the intermediate states, which is exactly the part nobody draws.

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

Draw both ends first

Generate the current architecture from the code and infrastructure as it is, and draw the target as you intend it. Having both in the same notation makes the difference legible, and it is common for the current-state diagram to be the surprise: the thing you are migrating from is usually not quite what people believed it was.

The intermediate states are the plan

The interesting question is not where you end up but what runs during the migration, because that is where dual writes, backfills and consistency problems live. Drawing the intermediate states makes the sequencing explicit, and the sequence is the plan. A migration document with only a before and an after has skipped the difficult part.

Find what depends on what you are moving

The usual cause of a migration overrunning is discovering a consumer nobody knew about. A generated diagram of the current state surfaces the dependencies that are expressed in code, which is most of them, early enough to be scheduled rather than discovered.

Then keep it current

A migration runs for months and the diagram drifts within weeks unless regenerating is cheap. Because this generates from the code, the current-state picture can be refreshed as often as the migration progresses, which is what makes it usable as a status artifact rather than a launch artifact.

Both states

shell

# Diagram the current architecture from this repository.
# Then: draw the target with the monolith split into orders, inventory and
# billing, and show the intermediate state where both run.

FAQ

Questions

Can it show a strangler fig pattern?

Yes, and the intermediate state is the diagram worth having: the facade, both implementations, and which traffic goes where at each phase.

Will it find all the dependencies?

The ones expressed in code and configuration. A consumer that calls you over HTTP from a repository you did not point it at is invisible, and that is often the one that hurts.

How often should the current-state diagram be regenerated?

Whenever a phase completes. Cheap enough that the honest answer is as often as anyone asks about status.

Onboarding Engineers to a Codebase
The first week is spent building a mental model that somebody already has. A diagram transfers it in an afternoon.
Documenting Legacy Code
Including the newest kind of legacy code: what a coding agent wrote for you over several sessions that nobody has looked at as a whole.
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.
System Design Interview Preparation
The diagram is the easy part. Interviews are decided by the tradeoffs you can defend when the interviewer pushes.