Meaning first, geometry second

A diagram with crossing edges and overlapping labels makes valid architecture facts hard to interpret. But a beautiful layout that reverses dependency direction is worse. First establish typed, directional relationships; then choose a consistent geometry that makes them legible.

Ports establish where an edge belongs

A port is an explicit attachment point on the boundary of a node. For a left-to-right dependency view, an outgoing edge normally leaves the right edge of a service and an incoming edge enters the left edge of its target. This makes the direction recognisable before someone reads the arrowhead.

Orthogonal routing uses horizontal and vertical segments to move around intervening nodes. It should preserve clearance and offer consistent bend treatment, rather than letting a line cut through unrelated services.

Two passes beat naïve placement

A first left-to-right layering pass can place most dependencies naturally. A subsequent right-to-left adjustment can address backward edges and reduce collisions. Cycles need explicit treatment; no simple topological order exists for a strongly connected component.

When service boundaries are shown, extra vertical spacing may be necessary. A layout that works with boundaries hidden should not be assumed to work when those boundaries are expanded.

A concrete routing example

Imagine a Service A at the left of a graph, consuming an API on the right. The ideal edge leaves Service A at its right-hand port, travels horizontally to a clearance corridor, turns vertically if necessary and enters the API at its left-hand port. Both the attachment and the arrow express the same logical direction.

Now put Service B between them. Drawing a direct diagonal line through Service B makes the relationship visually ambiguous. Orthogonal routing should find a corridor around Service B and allow enough distance from its border for the arrow to remain visible. A rounded corner can help the reader follow the line, but it cannot repair an arrow that attaches to the wrong node.

When three services share a provider, consider multiple incoming ports or careful route separation to avoid a tangle of identical vertical segments. Labels, if displayed, should attach to the relevant edge rather than float among neighbouring connectors. Hover detail should disclose identifiers and technology without forcing internal keys onto every node.

Layering, cycles and the right-to-left correction

Automatic placement usually starts from a graph's directed structure. A left-to-right layering pass gives a sensible baseline for paths that run from consumers to providers. That alone is not enough where a node is reached by several paths or an edge points backwards relative to provisional placement.

A second pass can revisit layers from right to left, move nodes into more appropriate positions and reduce reversals. It must balance edge length against crowded columns and crossings. If the graph contains a cycle, treat its nodes as a strongly connected component for layering or use another deliberate cycle representation; ordinary topological sorting cannot order a cycle.

These are heuristic choices, not a guarantee of a uniquely optimal layout. That is why explicit regression examples matter. Save expected screenshots of representative graphs, but also test that every edge still connects the right source and target regardless of the renderer's choices.

Service boundaries and selective expansion

A service boundary can clarify which components contribute to a service, but it introduces layout constraints that a flat graph does not have. Nodes may need more vertical spacing, a visible boundary label and room for edges to enter or leave the group without colliding with its children.

A collapsed service node and its expanded components should be mutually intelligible representations. Once expanded, a redundant summary block can obscure the very topology the user requested. When a user switches a technology or boundary filter, the graph should update predictably without resetting to an unrelated view.

For estate-wide maps, selective expansion is preferable to endlessly shrinking text. Start with services and the relevant connected objects; reveal further relationships when requested. Unconnected records should remain discoverable, but they need not dominate the visual centre. Every map should offer a clear way to clear selection and restore a readable viewport.

Why semantic parity is the acceptance criterion

A focused dependency graph and a large estate map often have different filters, but they should not contradict one another about a relationship's identity or direction. Reusing the same renderer where practical reduces subtle drift in ports, arrowheads, icon treatment and layout behaviour. Sharing one data contract is essential even if separate visual components are justified by scale.

A good acceptance test takes the same small estate, opens it in both views, and compares dependencies, tooltip content and project-context labels. If the result differs, the team must establish whether the difference is a deliberate filter or a defect. Graph quality is achieved by preserving meaning under changing perspectives, not by maximising decorative sophistication.

The estate-wide map should not be a different truth

A dependency view and an estate-wide map should ideally share a model and layout semantics. If one draws an API dependency in the opposite direction or exposes different technology labels, users lose confidence even if the underlying records are identical.

At larger scale, offer selective expansion, hover detail, stable selection and fit-to-view. Do not confuse “all nodes visible” with “all questions answered.”

The design argument is developed in Architecture as a Connected Knowledge Graph.