Generate an architecture diagram from a TypeScript project.
TypeScript projects usually have a real structure and a directory layout that obscures it, mostly because everything is a file that exports something.
What it reads
package.json for dependencies and entry points, tsconfig for path aliases, which is important because aliased imports hide the real dependency direction from anything doing naive text matching, and then the import graph from the entry points. Framework conventions supply structure: Next.js route files, NestJS modules and providers, Express router mounting, and any client instantiation that names an external service.
How TypeScript becomes components
The unit is a module that owns a responsibility rather than a file that exports a function. A directory of route handlers is one API component; a service class with its dependencies is one component; a data access layer is one boundary. Type-only imports are distinguished from value imports where possible, because a file that imports a type from another package is coupled at compile time and not at runtime, and drawing those identically overstates the coupling.
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.
Useful on code you did not write
A large share of TypeScript in circulation was generated over several agent sessions and never reviewed as a whole. Diagramming it is often the first time anyone sees the shape, and it usually surfaces the same two things: duplicated responsibilities in different directories, and a utility module that has quietly become the centre of the graph.
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.
TypeScript to diagram
| In the project | In the diagram |
|---|---|
| package.json | Dependencies and entry points |
| tsconfig paths | Resolves aliased imports to real edges |
| Next.js app or pages routes | The API and page surface |
| NestJS modules and providers | Components and their dependencies |
| Express routers | API components |
| Prisma or TypeORM schema | Data tier |
| Type-only imports | Distinguished from runtime coupling |
| *.test.ts, *.spec.ts | Not drawn |
The prompt
Questions
Does it need the project to compile?
No. It reads source files, so it works on a repository with type errors or missing dependencies, which is often exactly when you want to understand it.
Does it handle path aliases?
Yes, by reading tsconfig. Without that, aliased imports either disappear or resolve to the wrong place, which is a common failure in simpler tools.
Will it separate frontend and backend in a full-stack app?
Yes, into client and application tiers, with the API surface as the boundary between them. That boundary is usually the most useful line on the diagram.
What about a JavaScript project with no types?
It works. Types make the inference more reliable, particularly for distinguishing compile-time from runtime coupling, but they are not required.
Related
- 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.
- Generate a Diagram from a Django ProjectDjango's conventions are strong enough that most of the architecture is declared rather than implied, which makes it one of the easiest sources to read accurately.
- Generate a Diagram from a Next.js ProjectThe interesting line in a Next.js app is the one between server and client, and it is invisible in the file tree.
Last updated