Home >

Architects: Kill your arrows

Architects: Kill your arrows

Why, sometimes, you should just stick to boxes.

Posted on July 3, 2018 by Ernesto Garbarino

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

A bunch of boxes

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

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

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

A bunch of boxes with arrows

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

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.