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.
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
| Source | Becomes |
|---|---|
| pnpm-workspace.yaml, workspaces field | The package list |
| Internal dependencies between packages | Edges in the package graph |
| Cargo workspace members | Crates and their dependencies |
| go.work | Modules in the workspace |
| Nx or Turborepo project graph | A declared dependency graph, read directly |
| Per-package manifests | External dependencies of each package |
| Deployable entry points | The services worth their own diagram |
The prompt
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
- Generate a Diagram from a Python ProjectPython projects hide their structure in decorators and imports, both of which are readable and neither of which is visible from a directory listing.
- Generate a Diagram from a TypeScript ProjectTypeScript projects usually have a real structure and a directory layout that obscures it, mostly because everything is a file that exports something.
- Generate a Diagram from a Go ProjectGo's package structure is unusually honest, which makes it one of the better languages to read architecture out of.
- Generate a Diagram from a Rust ProjectCargo already knows the crate graph, so a workspace diagram is mostly a rendering of something the build system computes anyway.
Last updated