Generate from source

Generate an architecture diagram from a monorepo.

The hard part of diagramming a monorepo is not reading it, it is deciding what to leave out.

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

Start from the workspace configuration

Workspace definitions, whether pnpm-workspace.yaml, the workspaces field, a Cargo workspace, a go.work file, or a Nx or Turborepo configuration, already contain the package list and often the dependency graph between them. That is a far better starting point than walking the file tree, because it reflects the boundaries the repository itself declares rather than the ones the directory layout implies.

One diagram per boundary, not one for everything

A monorepo with sixty packages produces an accurate and unreadable picture. The useful outputs are a package dependency graph showing which packages depend on which, and then a per-service architecture diagram for each deployable. Those answer the two questions people actually have, which is what depends on this and what does this service look like inside.

Why the layout can be trusted

The agent reads the files listed above and emits a semantic graph: components, the tier each belongs to, and the edges between them, with no coordinates anywhere. The ELK layout engine then computes positions and orthogonal edge routing. This is why the output cannot come back with boxes overlapping or arrows crossing through cards, which is the usual failure when a language model is asked to place things on a canvas itself.

Finding the coupling you did not intend

The characteristic monorepo problem is a package that everything imports and that imports too much itself, so any change to it rebuilds and risks everything. That is obvious in a dependency diagram and close to invisible in a file tree, which makes this one of the few cases where the diagram tells you something you did not already know.

Your code stays on your machine

It runs on your machine. With a local Ollama model nothing leaves the laptop at all, and with your own API key the file contents go to the provider you chose and never through us. For a source that is your actual codebase, that distinction is usually the deciding one.

Workspace configuration to diagram

SourceBecomes
pnpm-workspace.yaml, workspaces fieldThe package list
Internal dependencies between packagesEdges in the package graph
Cargo workspace membersCrates and their dependencies
go.workModules in the workspace
Nx or Turborepo project graphA declared dependency graph, read directly
Per-package manifestsExternal dependencies of each package
Deployable entry pointsThe services worth their own diagram

The prompt

shell
$ Read the workspace configuration and draw the package dependency graph. Mark the deployable services and the packages that most things depend on.
FAQ

Questions

Should I diagram the whole monorepo at once?

Once, to see the package graph. After that, per service, because a single diagram covering every package is accurate and nobody reads it twice.

Does it understand build tool project graphs?

Yes, and reading a declared graph is better than inferring one, because it is what the build system actually uses.

Can it find circular dependencies?

They show up as cycles in the drawn graph. It is not a substitute for a linter that fails the build on them, but it makes the shape of the cycle much easier to understand than a stack of error output.

What about a monorepo spanning several languages?

It works, since it reads each package's own manifest. Cross-language edges expressed only at runtime, one service calling another over HTTP, come from configuration rather than from the dependency graph.

Related