How to read the map

Nobody at cleap has seen your code, and nobody has decided that this part of your product deserves to be in the middle or drawn larger. Every position, size and outline follows from what is in the repository. Two people with identical code get identical maps.

The closest thing to it is a contour map. Somebody chose the rules, and then the terrain decided the lines. If a region looks strange, that is the map reporting something about your code rather than making a choice about it, and it is usually worth a look.

It also holds still. A thing is where it was yesterday, so it is worth learning where things are. The rules that guarantee that are written up separately in the Stable Map Spec.

A folder holding two hundred files is drawn larger than one holding three, because it contains more. Size is not a judgement about which part matters, and it is not about how much traffic something gets or how often it changes. It is a count of what is in there.

With one adjustment worth knowing about. A folder with nine hundred files would otherwise get nine hundred times the area of a single settings file, and everything small would be squeezed into slivers too thin to read or click. So the difference is flattened: bigger things are still bigger, always, but the largest are not allowed to crush everything else off the page.

Size and importance are different things, and this catches people out. A tiny file that half your product depends on is still drawn small, because it contains almost nothing. Where it stands out is when you zoom out, which is section 6.

A group is not a box with things put in it. It is the other way round: the things are placed first, and then a boundary is stretched around them, like an elastic band pulled around a handful of objects on a table. So the shape you see is the arrangement of the contents, not a container anyone picked.

A ragged outline means the contents sit unevenly. The band is pulled inward wherever there is a gap between them, so every notch in the edge is a real gap inside. This is the common case, and the silhouette is worth reading: two lobes joined by a narrow waist usually means two clusters of work that barely touch.

A clean rectangle means the opposite: the contents fill their space evenly, so the band lands flat on the edge of the territory with nothing to pull it in. A group holding a single thing comes out square for the same reason, since that one thing occupies the whole space it was given. Square means tidy and full, not small.

No outline at all means nothing is inside. A single file or function is not a place with contents, so it is drawn as a marker rather than a territory. If something you expected to be a container has no outline, that is worth a second look, because it usually means it is empty.

Each thing is given a share of the space, and everything belonging to it is drawn inside that share. Its own contents then divide that space again the same way. This repeats down to individual files and functions, so at every level of the map, things drawn together really do belong together.

This is worth trusting because it cannot be violated. Nothing can drift outside its parent, and two neighbouring regions cannot overlap, so if two things appear to be in the same area they genuinely are related. A small gap is left between neighbours, which is why separate areas read as separate even before you notice the outlines.

Each thing sits at the centre of its own territory. Space is divided into shapes as close to square as possible rather than into long strips, for a plain reason: a tall thin sliver is hard to read the label of and hard to click.

• ScreensPages, components and routes people land on
• LogicFunctions, services and handlers doing work
• DataTables, queries and migrations
• OutsideThird-party services and SDKs you depend on
• SetupEnvironment, build and infrastructure

Colour never indicates health, quality or importance. It is only what sort of thing something is, so a region that is mostly one colour is telling you what that part of your product is made of. A large area of orange means a part of your system that leans heavily on outside services, which is a useful thing to notice without reading a line of code.

You cannot show fifty thousand things at once, so as you pull back, things drop away and only the ones worth seeing at that distance remain. What survives is decided by a blend of four signals: how many other things point at it, how much it contains, how near the top of the structure it sits, and how often it has been changing lately.

That is why a small file can be one of the first things you see. It contains almost nothing, so it is drawn small, but if much of your product depends on it, it earns its place early. Size answers “how much is in there”. Zoom answers “how much does this matter here”. They are separate questions and the map answers them separately.

A practical use for this. Zoom all the way out and read what is left, without clicking anything. That short list is a fair description of what your product actually is, and it is often not the list people expect.

Synced recently is the ordinary state, and means the area was read from your code a moment ago. Not re-checked recently means it was parsed a while back and has not been looked at since, so treat it as probably right rather than certainly right.

Last sync failed means exactly that, and the map may be wrong in that area. It is shown rather than hidden, because a map that quietly goes stale is more dangerous than one that admits it.

Nothing references this means the thing was found and read successfully, but nothing else in your code points at it. Sometimes that is dead code. Sometimes it is a job or a migration that is started from outside the code entirely, which the map already knows about and does not flag.

Most connections are read directly out of the code: this file imports that one, this function calls that one. A line crossing out to the edge of the map means something talks to a third party, and those are worth knowing about because they are the parts of your product you do not control.

Some connections are marked as inferred. Those were suggested by a model rather than found in the code, and they are drawn differently on purpose. A guess presented identically to a fact is how a map starts lying to you, so a guess is always labelled as one.

What actually ran. The map reads structure, not traffic. It shows the parts nothing has called yet, and it cannot tell you which path a request took last Tuesday.

Who owns what. On-call, team ownership and service tiers live outside the code, so no amount of reading it will find them.

Whether the code is any good. Nothing here is a quality judgement. A large ragged region is not a criticism, it is a description.

How cleap compares says which tools answer those questions instead.