Use case

Onboarding engineers to an unfamiliar codebase.

The first week is spent building a mental model that somebody already has. A diagram transfers it in an afternoon.

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
E-commerce platform architecture. 13 components across 5 tiers.
E-commerce platform architecture. Produced by the app's layout engine from a semantic graph, not placed by hand.

The situation

A new engineer joins and is pointed at a repository, a README written eighteen months ago, and whoever has time to answer questions. The information they need is structural, what the pieces are and how they connect, and none of the available artifacts present it structurally. So they read files, form a partial model, and validate it by making a change and seeing what breaks.

What to do instead

Generate the architecture diagram from the repository on their first day, together. The diagram is a prompt for the conversation rather than a replacement for it: the useful part is watching someone experienced correct it, because the corrections are exactly the tacit knowledge that never makes it into documentation. Ten minutes of that is worth a week of reading.

Then leave it behind

Export the corrected diagram into the repository. The next person gets the corrected version rather than starting again, and because regenerating is cheap it can be refreshed rather than rotting the way a hand-drawn diagram does.

Ask questions of it

Once the diagram exists you can ask what depends on a component before changing it, or what a request touches end to end. Those are the questions a new engineer has constantly and feels awkward asking repeatedly, and getting them answered from the code rather than from a colleague's memory is faster and more accurate.

Day one

shell
$ cd the-repo
$ lucid
# Diagram the architecture of this repository, and note what each component owns.
FAQ

Questions

Is a generated diagram accurate enough to onboard with?

As a starting point, yes: roughly what a strong engineer would produce after an hour of reading. The value is that it is produced in a minute and that correcting it surfaces knowledge nobody had written down.

Should it go in the README?

Yes, as an exported SVG. Regenerate when the architecture changes rather than when someone remembers.

Does the code leave the machine?

Not with a local model. That matters here specifically because onboarding often happens before a new engineer has been approved for every tool.

Related