The skill's demo map: a small parking-city system, whole-system floor.
This map shows how your code fits together, drawn as a factory. Each service is a factory building. The lines between buildings are the ways the code talks: a request, a stream, an event, a scheduled job, a read or write to a database.
The map is made from your committed code only, and it is stamped with one commit. It shows what the code says, not what runs in production.
Use Next or the → key to turn the page.
Floor 0 of a tiny example: two factories, orders and billing, with a belt from orders to billing. Scroll in on orders to open its floor of five packages.
Floor 0 is the whole system: every service, shared code on a shelf at the top, databases at the bottom, outside services on the right. Scroll in on a factory, or double-click it, to go inside; scroll out to come back up. Inside, the packages are the machines.
The Floors list on the left shows where you are; click a floor to go back up. Fit shows the whole floor.
Top, zoomed out on floor 0 and shown enlarged: the orders factory shows only its code, S1. Below, zoomed in on its file service.py: the class shows its code and its name, S1·P2·F2·C1 OrderService, and the doors name where its lines come from and go to, S1·P1 api and S1·P2·F1 rules.py.
Every item has a short code that says where it is: S2 is a service, S2·P1 a package inside it, S2·P1·F3 a file in that package; C is a class and M a method. Databases are D, libraries L, outside services X, topics T, in-process queues Q.
Zoomed out there is no room for names, so a machine shows only its code. Hover it, or zoom in, to see the name. Find takes a name or a code.
orders calls billing: a one-way belt, its chevrons pointing from orders to billing. billing and payments call each other: a two-way belt, chevrons both ways.
A belt is a request: one part of the code calls another and waits for the answer — an HTTP or RPC call between services, or a plain method call inside one. The chevrons point from the caller to the one it calls.
A belt with chevrons both ways is a two-way belt: the two call each other.
orders calls billing, payments and shipping: its belts leave as one trunk and fork at splitters. Those three all call reports: their belts join at mergers on the way. Splitters and mergers are the yellow plates.
When one part calls several others, their belts leave as one trunk and fork at a splitter. When several call the same part, they join at a merger. A trunk means "sends to those"; hover it to see how many lines and which kinds it carries.
orders streams to tracking: a blue pipe with a flange at each joint.
A pipe is a stream: data keeps flowing from one side to the other instead of one request and one answer.
orders produces events to the order-events hub on the green airfield. billing and reports each consume them on their own pad, and each gets its own copy.
A drone carries an event. The message broker is a green airfield; each topic is a hub in it. The producer launches from its pad; every consumer has its own pad and gets its own copy.
Drones fly over the floor, so their dotted flight paths can cross anything.
orders enqueues to invoices, a work queue with a waiting stack; billing and payments take from it in turn. billing's failures fly red to invoices-dead, the red-marked hub beside it.
A work queue is a hub with a waiting stack: each message goes to one of the workers, who take turns.
Dead letters: messages that failed fly in red to a red-marked hub beside their topic.
Top, floor 0: orders produces to order-events; billing's push subscription lands on its yellow receiving dock; reports pulls, its drone flying out to the hub and back. Middle, inside billing: the dock's sign names the endpoint the push calls, POST /events. Bottom, inside reports: the puller's tag, group orders-reports · 3 replicas.
With a push subscription the broker delivers to the service's yellow receiving dock, which names the endpoint it calls. With a pull subscription the service's drone flies out empty and comes back loaded.
A tag on a consumer such as 3 replicas says how many copies of it run.
Inside orders: the api package's routes enqueue to outbox, a hub on the service's own airfield with a solid edge; the workers package takes from it and calls the mailer.
An in-process queue hands work from one part of a service to another without a call between them: a queue, channel or hub that lives in the service's memory. It stands on the in-process airfield inside the service, never on floor 0: no other service sees it, and its items are lost when the service stops.
Its drones fly like events: a work queue keeps a waiting stack, and each item goes to one taker.
A nightly job in jobs writes to billing: the rail yard beside jobs with its platform to billing, a train on the track, billing's station, and the schedule sign reading daily 02:00.
A rail is a batch job: a cron job, or a job triggered to move data in bulk. Jobs leave from a rail yard beside the machine that runs them, one platform per destination with its job count. Each destination has a station.
The schedule sign on the yard sums up when they run (3 jobs · daily 02:00); hover it to list every job.
orders calls billing and reports along belts. It reads and writes orders-db, and reports only reads it. orders writes files to the receipts bucket, whose box carries the container yard, and keeps a cache only it uses: the chest beside it.
A database is a warehouse with a lane. A tap drops onto the lane: red writes, slate reads; a pair does both.
A cache used by one service is a chest next to it; a cache several services share sits in storage like a database. A bucket is a container yard; it is read and written by taps, like a database.
orders calls tax-api, a yellow dock on the right edge. payment-provider sends a webhook along a belt into billing's receiving dock. All three services call mail, so mail is the X1 tab on each of them.
Services outside your repo (a payment provider, a cloud API) are yellow docks on the right edge. A webhook is a belt from the outside dock into your service's receiving dock.
An outside service that three or more of yours call, and nothing else, is a small tab on each caller instead, so its lines do not cross the floor.
Left, floor 0: the library common on the shelf above orders. Right, inside orders: common is installed on the left wall, with a belt from the store package that calls it.
Code with no deployment of its own is a library. On floor 0 libraries stand on the shelf at the top. Inside a factory, each library it uses is an installed unit on the left wall, with belts from the packages that call it.
Code links (floor tools, off by default) draws thin dotted conduits from each service to the code it uses. A dotted line between two machines means one implements the other.
Four services. Where two belts cross between them, one passes under the other. The belt between payments and reports is inferred: its edge is dashed.
Where two lines must cross, one passes under: you see a hood on the tile before and after.
A dashed edge is inferred: the scanner reasoned that the line exists but did not see both ends in the code. Treat it as a guess. A red dashed straight line could not be routed: the connection is real, but no clear path was found for it.
Inside orders, eight packages all call audit, which wears used by 8. Its layer, S1·P1, is open, so its eight lines show. The layers button, bottom right, shows its code and a badge.
Some items are used by many others (8 or more). Their lines would bury the floor, so each gets its own layer, named by the item's code, here S1·P1. The item wears a used by N badge.
The layers button (bottom right) appears only on floors that have one. Pick a layer: its lines show on top, the rest fade. Esc or a click on empty floor goes back to the base.
Two factories: click orders to keep only what it touches, click empty floor to clear it, scroll in on orders to go inside, then scroll out to come back up.
Click a machine to keep only what it touches; the panel on the right says what it is, where its code lives and what it connects to. A click on empty floor or Esc clears it.
Scroll in on a building to go inside it (or double-click it); scroll out past the whole floor to go back up a floor.
Write a comment on anything, then Save for the agent. It saves export-comment.md into docs/viz-code/, next to code-map.json (if your browser downloads it instead, move it there). The next time you run the skill, the agent reads it first.
The pinned trace "a customer pays for an order": orders calls billing's create_invoice, which rounds through the common library (folded: 2 calls), writes the invoices table and calls payments. Below, create_invoice opened in the detail panel with its example request and response.
A trace follows data from any box on the map: upstream to what feeds it and downstream to what it feeds. Select something and press Trace in the inspector. A method, table, topic or outside service starts from itself; a service, package or class from its entry points, else from the methods where lines cross its edge, and the head says so ("billing · service · 2 entry points"). A service also lists its entry points, each with its own Trace button. The screen splits: the floor stays above, the trace below. Drag the divider, or press Maximize.
The floor and the trace show the same thing. Starting a trace clears the selection. Click any box on the floor and the trace starts there instead, in the same direction; click a line and it starts from both its ends; click the box the trace already starts from and nothing changes. One box wears the blue ring at a time: the row you clicked in the trace, else the trace's start. The inspector on the right shows that same item, so a comment you add there is about it.
Boxes are services and libraries, with their methods inside; a table, topic or outside service is a box of its own. Inside a box a call goes down; to another box it goes right. Each method says what arrives: the parameter types going in, the return type coming back. Dashed arrows are guesses; ↺ marks a loop. Drag the background to move around; Ctrl+wheel or a pinch zooms, and Fit trace shows the whole trace.
The trace starts two steps each way. + goes one step further. A method with more than five neighbours shows the total, then five, then show all. Calls into a shared library fold into one box until you open it. "Entry method not known" means the map only knows which service it reaches.
Click a method or an arrow to see its examples: made-up values, one per entry point and one per data type, always labelled example values, not computed. The floor rings the method you clicked, moving to it when it is out of sight; when it is on another floor the detail panel says which, the door that way is ringed, and Show on floor takes you there floor by floor. Pin keeps a trace in Pinned traces on the left; Save for the agent sends your pins with your comments. Esc closes the trace.
What the map can't do
Keeping it current
How to run it