TopoMap draws a diagram from a model.json. The file is written by a Claude Code agent skill that reads your codebase; this page is only the viewer.
Getting a model
- Install the skills. They live in my github repo
- Open a project Claude Code can read. Supported today are Spring Boot (Gradle or Maven, Java or Kotlin) and Angular workspaces (with or without Nx).
- Run the skill that fits:
/mw-topomap-springboot or /mw-topomap-angular. It works through the code in four detail stages (below) and stops after each one to ask whether to carry on. Those answers decide how much the model ends up carrying. - Load the
model.json here, by dropping it anywhere on the page or with add model. Up to five can be open at once.
The descriptions can be in any language the agent writes. The first thing the skill asks is which one, and it covers everything the skill writes itself: class summaries, method docs, arrow labels and use case notes. Class, method and column names stay exactly as they are in the code, and this page - buttons, column headers, section titles - stays English. The answer is kept in the model as meta.language, so a later run on the same project does not ask again.
The four detail stages
A model is finished and handed over after every stage, so a map can stop at any of them. What a model does not carry yet is greyed out rather than missing - the switches in the panel on the left are disabled and say why.
- stage 1
- Modules and classes. The lanes, the classes in them and their stereotypes - the shape of the codebase, nothing inside it yet.
- stage 2
- What the classes offer. Members, signatures, routes and entity columns, so a class can be read on its own and the panel on the right has something to show. Below this, component members is disabled. It is also where the first findings appear - see below.
- stage 3
- How they are connected. The arrows between classes and modules, with their labels. Below this, connections and arrow labels are disabled.
- stage 4
- The use cases. The clickable paths through the system. Only a stage 4 model has them - below that the button reads no use cases yet.
Stages 2 and 4 are the expensive ones, together about 80% of the writing, which is why the skill asks before it starts them. The number in brackets on a tab is the stage that model reached.
In a hurry? load springboot example on the start screen opens one Spring Boot project in all four stages at once, so you can see what each stage adds before running a skill on your own code.
Reading a map
- Click a class to open the panel on the right: what it offers, who calls it, what it calls, and the use cases it takes part in.
- Click a module header to fold that lane away, and use the panel on the left to hide whole modules or stereotypes. A hidden column disappears with it, so the diagram gets narrower and you can zoom in further.
- Show use cases picks one path through the system and lights it up across the modules, with the steps numbered in the panel - stage 4 models only.
- Show findings lists what the skill noticed on the way through the code - coupling, boundaries, transactions, classes that grew too big. A click on one lights up the classes it is about, the same as a use case does with its path. They start at stage 2 and get more specific with every stage after it, and each one names the evidence it was read from - a finding without one would be true of any codebase.
- Search in the header dims everything that does not match - it looks through class names, members, routes and docs.
- Drag to pan, wheel to scroll, cmd/ctrl + wheel to zoom, and fit to bring the whole diagram back into view.
- Click TopoMap in the header to put one map back exactly as it opened.
- export png on a module header saves that module as an image, and export whole map as png in the panel saves all of it. Both are rendered at full resolution regardless of the zoom, in the theme you are in, and with whatever you have hidden left out - so filter first, then export.
A model is editable
It is plain JSON. If the skill got a label wrong or missed an edge, fix it in the file and load it again - and read the "model issues" box in the panel, which lists what the renderer had to repair.
