One map of a project that lives in several repositories

The rest of this page is a walkthrough, recorded against fixtures/multi-repo, the demo project measured above: four services that do not share a repository, small enough to read in a sitting, and already carrying the kinds of problem a real project has. A scene is a shell script, so what is on screen is what actually ran.

02Build

build reads every repository in its own process and joins the readings. A first build is rarely all green, and it is not supposed to be.

Three of the seven calls between services joined; one goes to PAYMENTS_URL, which no service claims. Four of thirteen browser requests found their route. The last line counts what is left: missed places the reader could not join, notes on joins it made from a name alone, and findings about the code itself. Nothing was guessed; all of it was recorded, with a file and a line.

03Ask what it could not read

doctor turns those counts into a list of things to do, grouped by cause. Every row names the reason, the file, the line, the call, and what to change.

Three browser calls could go to two services, so it asks which one the frontend's apiUrl names. PAYMENTS_URL is a setting no service claims, and doctor --missing names the repository it probably belongs to. And ORDERS_URL was joined to orders only because of its name, which is kept as a note until the configuration says so outright.

flowatlas doctor --reason <code>  # one kind of gap
flowatlas doctor --missing          # the repository missing
flowatlas accept route-unguarded --service orders
flowatlas doctor --strict           # exit 1 past the baseline

04Answer it in the configuration

Two settings join two more browser requests, reach one more route, and turn both notes into facts.

baseUrlEnv says which settings keys other services use to address a service. Without it, a key named after a service is still joined to it, and doctor keeps a note saying only the name chose it; a key named after nothing is joined to nothing. apiTarget does the same for a browser, saying which service a frontend's settings key points at.

What survives is no longer missing configuration. It is the project disagreeing with itself, which is the thing worth knowing.

05Follow one request

flow takes any way in and follows it until it stops.

The first trace starts at a (click) in an Angular template and ends at a row in a table in a different repository, crossing two service boundaries on the way, with unresolved on this path: 0 to say nothing along it was guessed.

The second shows the other case. BillingClient builds its address at run time from a registry, so nothing can be read from the source; an annotation on the method declares where it goes, and the edge is recorded with confidence: marker rather than static, so it is always clear which edges were told rather than found.

The second also shows billing calling back into orders for the order it invoices: three repositories again, one of them twice.

An entry can be named however you would say it aloud. These three are the same route:

flowatlas flow "POST /orders/12345/archive"
flowatlas flow "POST /orders/:param/archive"
flowatlas flow "entry:orders:http:POST:/orders/:param/archive"

06Ask the other direction

impact starts at a symbol and walks backwards to every way in that reaches it. Give it a table and it tells you which routes would have to be retested.

hotspots ranks what the most things point at, and channel shows both ends of a message channel — here order.created, published in orders and handled in billing, whose handler calls back into orders for the order it was told about.

07Compare what crosses a boundary

Two services agree about a shape until one of them changes. contracts compares what each side of every crossing declares, field by field.

No boundary in the demo disagrees, and the unchecked list is why that is worth believing: it says which boundaries could not be compared and what to do about each — a literal where a typed value would do, a call that says nothing about what it expects back — rather than reporting them as agreement.

types --drift finds what a compiler in one checkout never can: InvoiceDto declared one way in billing and another in the gateway, and OrderDto in the shared package and again in the web app. contracts compares the two field by field.

08See the shape of the whole thing

dead is the one to read carefully. It says so itself: nothing in it is proof, every row is a heuristic with the reason it fired attached.

visualise writes one self-contained page: no server, nothing to fetch, nothing to install. It opens on a Map of the services, lists every way in, and follows any one of them across service boundaries, marking each crossing with what it was joined by and how much to trust it.

It is a report you can click, not a viewer you keep running. Attach it to a review, or keep it beside a decision.

It opens on a Map: one box per service, queue, table and outside host, laid out in the order a request travels, joined by what passes between them and counted. A check marks what to look at — routes nothing calls, channels with one end, services that reach each other — and, once traces are laid over it, a heat colours each link by its traffic or its p95. Start here offers the busiest way in and the worst gap.

Steps shows one way in as a list in call order: each table, address and channel inline, calls side by side or once per item of a loop, what it can fail with, and — where traffic went through — how often it ran and how long it took; Waterfall draws the same steps on a time axis. Copy as prompt hands it to an assistant as Markdown. Not joined lists what did not join, grouped by cause, with the risks found in the code and what was accepted. Busiest ranks the methods most things lean on, Traces draws real requests one by one, and the Graph tab shows any node with what it takes and gives back, each type opened field by field. --diff <ref> adds Changes and --observed-diff adds Run time changes. One search box above the tabs finds a route, channel, table, type, gap or class, and goes to it.

The page above is the demo project with its sample traces laid over it (scene 10): scripts/demo/page-project.sh builds it and scripts/demo/page-tour.mjs takes the pictures.

09Ask what a branch changes

diff builds the graph at two revisions and reports what moved between them.

One route is renamed in the orders service. flowatlas names every way in that reached it — the gateway route, billing's handlers and the browser button above them, in repositories the change does not touch — and shows each flow it cuts as the steps before and after, drawn as a sequence diagram in the Markdown. The output is Markdown because its destination is a pull request comment; --fail-on-contract-break and --fail-on-rule-break make it a build failure instead.

flowatlas diff main               # this branch against main
flowatlas diff main --section impact  # only who would notice
flowatlas check --env production  # safe to deploy there?
flowatlas rules                   # who may call what

10Lay what really ran over it

Everything so far was read from code. observe adds what real traffic did — from OpenTelemetry, Zipkin, Jaeger, @nestjs/observe, a test run's HAR files or AWS logs — and lays it over the map: how often each join ran, how long it took, how it answered. A trace never draws an edge; what it shows that the code does not is listed as a question.

Twenty-nine spans from three files: the joins they ran, the slowest ways in by p95, and three things traffic reached that no reader drew — a collection, a metrics route and a queue. One route answered 500 that nothing in its code says it can; doctor names it, and the page puts the same counts and timings on every step.

flowatlas observe test-results  # a Playwright run's HAR files
flowatlas observe --listen      # OTLP on 127.0.0.1:4318

Run time in five minutes goes from an end-to-end test run to that picture.

11Give it to an agent

init already registered the server in each repository. An agent in any one of them gets the whole project over the Model Context Protocol.

Twenty-six tools in all, and a session lists the ones its project can answer: nineteen here, until traces are laid over it or rules are written (flowatlas mcp --all-tools lists every one). Only one of them returns source code. A trace never drags in the body of every method along it; the agent asks the graph which name to look at, then asks for that one name.

flowatlas mcp --install   # register everywhere, merging
flowatlas mcp --install --dry-run

After that, claude mcp list shows flowatlas. docs/mcp.md is the whole thing: setup for Claude Code, Cursor, VS Code and Claude Desktop, what each tool takes, the order to call them in, and what to check when a client will not list the server.