15 Rules for Perfect Architecture Diagram Arrows

I built an engine that checks architecture diagram arrows against 15 quality rules. Then I ran it on my own 52 diagrams.

41 failed.

Not “borderline.” Failed. Crossed arrows. Diagonal segments. Edges routing through shapes. Exit points bunched together. After spending weeks building what I thought were clean diagrams, a programmatic checker proved that 79% of them had routing issues a human eye glosses over.

Here are the 15 rules. Every diagram I ship now passes all of them.

The 3 Critical Rules (Zero Tolerance)

These three rules have zero tolerance. Violate any one of them and the diagram looks amateur, regardless of everything else.

Rule 1: Orthogonal Only

Every segment of every edge must be either perfectly horizontal or perfectly vertical. No diagonals. No curves. No “close enough.”

The test: Take any two consecutive points on an edge path. Either their X coordinates are identical (vertical segment) or their Y coordinates are identical (horizontal segment). If both differ, the segment is diagonal.

Why it matters: Diagonal edges look unintentional. They suggest the tool auto-routed the edge and nobody reviewed it. A single diagonal segment in an otherwise clean diagram breaks the visual consistency.

The fix: Insert a waypoint at the bend point to split the diagonal into two orthogonal segments. Choose the L-shape (horizontal-first or vertical-first) that creates fewer crossings with other edges.

Rule 2: Zero Crossings

No two edges may intersect at any point along their paths.

The test: Decompose every edge into horizontal and vertical segments. For every pair of edges, check all H-V segment pairs. A crossing occurs when a horizontal segment’s Y value falls between a vertical segment’s Y endpoints AND the vertical segment’s X value falls between the horizontal segment’s X endpoints.

Why it matters: Crossed edges force the reader to trace which line goes where. With more than two crossings, the diagram becomes a puzzle instead of a communication tool.

The fix: Re-route the shorter edge by adding waypoints that go around the crossing point. Use the “highway” pattern - route the edge outside the main diagram area, then back in.

Rule 3: Zero Edge-Through-Shape

No edge segment may pass through the bounding box of any shape that is not the edge’s source or target.

The test: For each edge segment, check intersection with every non-source, non-target shape. A horizontal segment at y=100 from x=50 to x=300 passes through a shape at (120, 80, 160, 60) because the segment’s Y is within the shape’s vertical bounds and the segment’s X range overlaps the shape’s horizontal bounds.

Why it matters: This is the most egregious violation. An arrow that goes through a box looks broken. It’s the first thing anyone notices. It screams “nobody reviewed this diagram.”

The fix: Add two waypoints that route the edge around the shape, maintaining at least 20px clearance. Route below (shape.bottom + 20), above (shape.top - 20), or to the side.

The 4 Routing Quality Rules

These affect how professional the routing looks. They’re the difference between “acceptable” and “polished.”

Rule 4: Minimal Bends

Each edge should have the minimum number of bends needed to reach its target without violating Rules 1-3. Extra bends add visual noise.

The test: For each edge with N waypoints, simulate removing each intermediate waypoint. If the path is still valid without it, the waypoint is unnecessary.

Rule 5: Consistent Exit/Entry Points

When multiple edges exit the same side of a shape, they must be evenly distributed. Not all bunched at the center.

The formula: For N edges exiting the same side, position each at (i + 1) / (N + 1). Three edges from the right side should exit at Y positions 0.25, 0.50, and 0.75. Not 0.33, 0.50, 0.67. And definitely not all at 0.50.

Why it matters: Bunched exit points create overlapping edge segments near the shape. The first few pixels of each edge look like one thick line instead of separate paths.

Rule 6: Symmetrical Fan-Out

When one source connects to multiple targets, the routing pattern must be visually symmetrical around the center axis.

The pattern: All edges exit the source at evenly distributed points. All edges travel to a shared “highway” line (a vertical or horizontal guide). Each edge turns on the highway toward its target. The result: zero crossings, perfect symmetry.

Rule 7: Symmetrical Fan-In

Same as Rule 6 but reversed. Multiple sources converging on one target must enter at evenly distributed points with symmetrical routing.

The 3 Spacing Rules

These control the whitespace around edges. Tight diagrams with edges brushing against shapes look cramped and hard to read.

Rule 8: 20px Clearance

Every edge segment must maintain at least 20px distance from any non-source, non-target shape boundary.

The test: For each edge segment, find the closest shape boundary that isn’t the edge’s source or target. If the distance is less than 20px, the edge is too close.

Why it matters: Tight clearance makes it ambiguous whether an edge connects to a shape or just passes by it. 20px of whitespace removes the ambiguity.

Rule 9: No Overlapping Edges

Two different edges may not share the same path segment. Parallel edges on the same line look like one thick edge.

The fix: Offset parallel edges by 10px perpendicular to the shared segment direction. Two horizontal edges at y=100 become one at y=95 and one at y=105.

Rule 10: Label Placement

Every edge label must be centered on the edge’s longest segment, not overlapping any shape, and have a white background so the label is readable even where it crosses the edge line.

The 5 Polish Rules

These are the finishing touches. They distinguish “good” from “publication-ready.”

Rule 11: Flow Direction Consistency

The primary flow direction must be consistent. If the diagram flows left-to-right, more than 70% of edges should follow that direction. Feedback loops and secondary relationships are exceptions.

Rule 12: Edge Ordering Preservation

Parallel edges connecting the same columns of shapes must maintain their vertical order. If edge A’s source is above edge B’s source, edge A’s path should remain above edge B’s path at every point.

Rule 13: Right-Angle Precision

Every bend must be exactly 90 degrees. This is guaranteed by Rule 1 - if all segments are orthogonal, all bends are right angles.

Rule 14: Connection Point Accuracy

The first waypoint of each edge must exactly match the calculated exit point on the source shape. No floating-point drift. exitX=0.5 on a shape at x=100 with width=200 means the edge starts at x=200. Exactly.

Rule 15: Waypoint Grid Alignment

All waypoints must be on the 10px grid. Round every coordinate: x = Math.round(x / 10) * 10.

How I Check These Programmatically

I wrote a TypeScript engine that parses .drawio XML, extracts all vertices and edges, decomposes edge paths into segments, and runs every rule as a geometric check.

// Rule 2: Zero Crossings
// Check every pair of edges for H-V segment intersections
for (const segA of edgeA.segments) {
  for (const segB of edgeB.segments) {
    if (segA.direction === 'H' && segB.direction === 'V') {
      if (segA.y > segB.minY && segA.y < segB.maxY &&
          segB.x > segA.minX && segB.x < segA.maxX) {
        violations.push('CROSSING');
      }
    }
  }
}

The scoring: 30 points for Rules 1-3 (critical), 25 for Rules 4-7 (routing), 25 for Rules 8-10 (spacing), 20 for Rules 11-15 (polish). Pass threshold: 95 out of 100. Not 70. Not 80. One crossed arrow in a professional diagram is one too many.

The Results on My Own Diagrams

I ran this engine on all 52 diagrams across my site. The results were humbling:

The diagrams that scored 100 were all simple left-to-right horizontal flows. Easy routing. No fan-out. No feedback loops. The moment a diagram had more than one flow direction, the auto-router started creating violations.

The fix for every failing diagram was the same: add explicit waypoints to each edge instead of relying on the auto-router. When you specify the exact path, the path is exact.

What I’d Recommend

Start with Rules 1-3. If your diagrams have no diagonal segments, no crossings, and no edges through shapes, they’re already better than 90% of architecture diagrams in the wild.

Then add Rule 5 (exit distribution) and Rule 8 (clearance). These two rules account for most of the “it looks off but I can’t explain why” feeling in diagrams.

Finally, enforce Rule 15 (grid alignment). When every waypoint snaps to a 10px grid, the entire diagram feels ordered even if you can’t articulate why.

The remaining rules are polish. They matter for publication. They don’t matter for a whiteboard sketch.

And if you want to skip all of this: describe your Azure project and let the tool draw the diagrams for you. Every diagram it generates passes all 15 rules by construction.

---

For the full enterprise diagramming approach, see 20 Architecture Diagrams in 20 Minutes. For the technical pipeline behind these diagrams, see Architecture Diagrams with Draw.io MCP and Claude.