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. The map marks the same thing while it is open - the arrows that touch the class and the classes at their other end - and a name in that list jumps to it, even if a filter had it hidden.
- 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. The map moves to the path, and a step in the panel jumps to the class it names. A finished model brings around thirty of them, so the list has a filter at the top; if it narrows down to one, enter opens it.
- 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 and moves the map to them, the same as a use case does with its path, and the list has the same filter - severity, category and class names are all in it. 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 and rings what does - it looks through class names, members, routes, docs, the module and the stereotype. How many classes matched is shown in the bottom left corner of the map.
- Drag to pan, wheel to scroll, cmd/ctrl + wheel to zoom, and fit to bring the whole diagram back into view. From the keyboard: tab to the map, then the arrow keys pan (hold shift for larger steps), + and − zoom, 0 fits. Escbacks out of a use case, a finding, and then the panel.
- Click TopoMap in the header to put one map back exactly as it opened.
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.
