Redesigning the
Service Dependency Graph.

1. What the product does. Specmatic helps engineering teams work with API contracts and verify that services actually communicate the way those contracts say they will. Insights is the visibility layer on top of that — and the Service Dependency Graph is the part of Insights that shows which services depend on which, a logical contract-relationship graph, not a runtime infrastructure map.
2. Who relies on it. Not one type of user — backend/API developers, contract owners, platform engineers, architects, EMs, QA/test teams, DevEx/governance teams, SREs, and engineers new to a codebase all use this graph, each with a different job: find a service, assess blast radius, scope regression tests, understand ownership, or just get oriented in an unfamiliar system.
3. Why the complexity is real, not invented. The intended scale is 100–5000 services with only ~12–24 visible at a time. That's not a hypothetical edge case — it's the baseline the graph has to work at from day one, which means "more services" reliably means "more relationships, more visual noise, harder navigation."
4. Why this needed a redesign, not a visual refresh. The existing graph's problems weren't cosmetic. Nodes could exist with no visible relationships and no explanation why. The canvas didn't use its own space efficiently. Controls were permanently present regardless of whether the current view needed them. These are structural, information-hierarchy problems — repainting the same toolbar wouldn't have fixed any of them.

The original graph toolbar carried a View dropdown, Previous and Next buttons, and an Export action — all competing for the same visual space as the graph itself, alongside search, filters, and the graph controls that actually mattered for navigation. A user opening the graph to answer "what does this service depend on?" had to visually filter out four controls that had nothing to do with that question before they could even start.

The easy move here would have been a visual refresh — restyle the same toolbar, tighten the spacing, call it done. That was set aside quickly: the problem wasn't that the controls looked cluttered, it was that they were cluttered with the wrong things. Restyling doesn't fix a control competing for space it hasn't earned.

The real question wasn't "how do we fit these controls in more neatly" — it was "does this control directly help the user understand or navigate the dependency graph?" Anything that didn't clear that bar came out entirely, rather than being made smaller.

View dropdown, Previous, Next, and Export were removed outright. What remained — total service count, search, zoom, fit, reset, filters, and the graph itself — earned its place because each one maps directly to a step in the actual user task (find → understand → navigate → orient → focus). Search was kept but narrowed by roughly 20%, sized as a fast path to a specific service rather than a dominant toolbar element. Filters were rebuilt as compact, canvas-anchored elements instead of a toolbar row, so the graph — not the chrome around it — stays the dominant visual element.

In the current build, navigation aids don't yet track the user's actual context. A directional control sits on screen at all times regardless of zoom level, and there's no minimap at any zoom level — so on a small graph the interface still carries navigation weight it doesn't need, while on a large, deeply-zoomed graph, there's nothing to answer "where am I relative to the rest of the system?"

The default pattern most graph tools reach for is a permanent minimap, always in the corner. That was ruled out — for a graph that's frequently small or simple, a permanent minimap is a second navigation layer the user doesn't need yet, and it takes up canvas space that could go to the graph itself.

The guiding question became "when does a navigation aid actually justify the screen space it takes?" — not "should this feature exist," but "when should it appear." That produced two explicit, testable conditions instead of an always-on/never-on binary: the 4-key directional pad appears only once the user is sufficiently zoomed in, positioned just above the bottom toolbar with Down directly under Up so it reads as a deliberate controller, not a scattered set of arrows. The minimap appears only when zoom exceeds 150% and the graph has more than 50 nodes — the two conditions under which a user is genuinely likely to lose spatial context.

Both aids go from either permanently present or entirely absent to conditionally available exactly when the graph's complexity justifies them — small and simple graphs stay clean, while large, zoomed-in graphs get the orientation support they need without that support existing as visual noise the rest of the time.

The graph was bound by the surrounding webpage. Any real exploration — following a long dependency chain, comparing spread-out clusters — meant working inside a canvas that was smaller than the problem it was trying to represent, with no way to reclaim more space.

The straightforward version of "give it more room" is simply making the graph bigger — expand the card, shrink the surrounding page. That alone wasn't enough: making the canvas bigger without carrying navigation controls (fit, reset, zoom) and a clear exit path into that bigger view just relocates the original problem into a larger box.

The distinction that mattered was fullscreen as an exploration mode, not a magnification setting. Going fullscreen needed to preserve every navigation aid the user relies on in the normal view — bottom navigation, fit, reset — and needed an unambiguous way back out, rather than trapping the user in an enlarged canvas with no clear exit.

The graph now supports Normal webpage → Graph section → Fullscreen graph as a deliberate escalation path. The Insights dashboard context stays intact until the user chooses to leave it, and fullscreen carries the same bottom navigation and recovery controls (fit/reset) as the standard view, with an explicit way to exit back to the dashboard.