Architects: Kill Your Arrows

Share on:

Good old boxes and arrows. Love them or hate them. Undoubtedly, an avoidable sight in most, if not all, “architectural diagrams”.

Before the reader invokes the working software over comprehensive documentation principle from the Agile manifesto to abruptly end the discussion, let me clarify that architects don’t do software design; we “draw” to communicate, orientate and facilitate decision making. Proper “design”, instead, is the domain of software engineers, with or without the use of a pictorial approach.

The models that we do in architecture have the objective of highlighting the salient features (or properties) of an architecture—toward which we want to draw the audience’s attention. This means that the model is more about what it hides—what it abstracts away from—than what it shows.

A bunch of boxes

Using just boxes, we can communicate a significant amount of information depending on how the boxes are arranged and labelled:

  • A collection of adjacent boxes represents a number of related elements
  • A large box, relative to a small one may represent a higher degree of importance or a larger volume
  • The use of colour in the background and border may add two additional dimensions of information such as category, type, degree, importance, etc.
  • The use of a non-solid border (e.g dashed line) may tell whether the element is optional or incomplete
  • The vertical position of a box may imply rank or order
  • The horizontal position of a box may imply rank, order or an event in a time series
  • Boxes within boxes convey Venn diagram-like subset semantics
  • Overlapping boxes convey Venn diagram-like intersection semantics
  • The labels' box format (bold, italics, etc) may provide yet another dimension

It is fair to say that the use of colour, among others, is not self explanatory and may require a “legend box” compartment within the diagram. Arrows, however, are seldom explicitly clarified in the same way that colour coding is. We sort of assume that everyone understands what an arrow means. Wrong. Arrows are often misleading and introduce false implications.

Let me give you an example. In the below diagram, it appears that traffic flows from the front end, it reaches a circuit breaker, and then, a set of microservices. Even if circuit breakers were implemented in a Service Mesh layer, this is still conceptually misleading since circuit breakers are used, more often than not, in the context of microservice to microservice interaction. The arrow makes the circuit breaker appear like a firewall or a load balancer.

Hiding unnecessary details

By killing the arrow and including the circuit breaker as a capability, I abstract away from the traffic flow dimension. Now the intuition that any microservice may benefit from circuit breaking capabilities—rather than just those exposed to the public—is clearer.

Unless explicitly specified, arrows can be interpreted in too many different ways so it is best to avoid them altogether unless we are dead sure that we want to surface a concrete architectural dimension through them.

A bunch of boxes with arrows

Some of the way in which arrows may—wrongly—be interpreted include:

  • The flow of information in the arrow’s direction(s)
  • That, unless a double arrow is used, information flow is only unidirectional but a single arrow is assumed to be bidirectional if it describes a request/reply mechanism like HTTP
  • That an element A can invoke an element B if connected by an arrow or vice versa (e.g. UML dependency)
  • Either a loose or hard relationship between the connected elements (ambiguous)
  • That element A descends from element B if the arrow points from A to B (UML interpretation) or the other way around (common sense without UML bias)
  • That an unfilled arrow represents sub classing (UML interpretation) or that unfilled arrows is just a cosmetic aspect (common sense)
  • That an arrow using a dashed line implies a dependency (UML interpretation) or that it is optional (common sense)

In conclusion, if architects are criticised for drawing too many boxes and arrows, by dropping the arrows not only we achieve better abstraction, but we also get to be criticised on one account only. Happy modelling.