// case study 03

Live Topology Map: a dependency graph that lays itself out

During an incident, a table of services hides the one thing you need to know: what sits upstream of the thing that just went red. This map draws the system as a graph automatically, so the picture stays correct as services are added or rewired.

Role
Designer and engineer
Origin
Public rebuild of the System Map I designed at Disney
Stack
React 18, TypeScript, Vite, SVG, WebSocket, Vitest
Data
Invented sample topology, built-in simulator

Background

At The Walt Disney Company I built a System Map component in the Apex platform that shows the real-time health of every connected device on the network. I designed the graph algorithm that parses device responses and maps each node's upstream and downstream position, and the leader lines operators use to trace dependencies at a glance.

That code is private. This is a clean-room public version of the same idea, with invented services, hosts and numbers, so the approach can be read and run.

The layout algorithm

Each service only declares what it receives from. Everything else is derived, in five steps:

  1. Edges. Build directed edges from each upstream to its service. References to unknown ids are reported instead of crashing the map.
  2. Columns. Run Kahn's topological sort and take the longest path from any source, so every service sits one column right of its deepest upstream.
  3. Cycles. Anything the sort can't order is on a cycle. Those services go into a final column and the UI shows a warning, so bad data is visible rather than hidden.
  4. Row order. Alternating barycenter sweeps move each card toward the average row of its neighbors, left to right using upstreams and right to left using downstreams.
  5. Transpose pass. Swap neighboring cards in a column whenever that lowers the crossing count, cleaning up what barycenter leaves behind.

The layout only recomputes when the graph's shape changes, not on every metric update, so cards don't jump around while data streams in.

Leader lines

The cards are ordinary flexbox columns, not absolutely positioned. An SVG layer underneath measures each card and draws a cubic Bezier from the right edge of the upstream card to the left edge of the downstream card. A ResizeObserver re-measures when a card or the window changes size.

Lines take the color of the worst health at either end, and selecting a card dims everything unrelated, so the path from a failing service back to its cause stands out.

Keeping layout in CSS and drawing only the lines in SVG means the cards stay real, focusable HTML instead of shapes on a canvas.

Live data

The client takes three message types over a WebSocket: a full snapshot, a patch, and a metric sample. A reducer applies them to the current state. The connection reconnects with exponential backoff.

A built-in simulator produces the same messages, so the demo runs with no backend. Pointing VITE_FEED_URL at a real server switches it over.

Each card shows identity and health on the left and metrics on the right, ordered inputs first and outputs last. A load sparkline appears only when there is data to draw.

Accessibility

  • Every card is a button, so it is reachable and operable by keyboard.
  • Each card's accessible name includes its health, so screen reader users hear status, not just a color.
  • Health is shown in text as well as color, the same rule I followed on the Disney version.

Testing

The layout and the feed reducer are pure functions, which makes them easy to test. Vitest covers column assignment, cycle handling and the crossing count, so changes to the algorithm can't quietly make the map harder to read.

Next steps

  • Pan and zoom for large graphs
  • Grouping services by zone or team
  • Keeping the selected card in the URL so a link opens the same view