Visualizing Microservice Architecture

Use a visual model to express the complexity of a microservice architecture

Complexity in software systems is an unavoidable pain. In conference presentations, blog posts and especially in our Microservice Architecture book, we in the API Academy have discussed techniques for dealing with complexity in the context of microservices. In particular, we've cited Fred Brooks’ delineation of complexity into the essential complexity that is inherent in the business problems a software system solves and the accidental complexity resulting from implementing that solution.

As I work more closely with organizations who are adopting “API-first” engineering practices and microservice architectures, I find this delineation increasingly useful. Firstly, by separating the complexity in this way, it allows architects and engineers to focus on minimizing the system’s accidental complexity.

The technological innovations associated with microservices help tremendously here: containers, automation tools, API management platforms. But what I really like about this complexity demarcation is that it helps us face an inconvenient truth: no technology—no elusive silver bullet that Brooks refers to in the title of his paper—is going to reduce a system’s essential complexity.

“Many of the classical problems of developing software products derived from this essential complexity and its nonlinear increase with size.” — Fred Brooks, No Silver Bullet—Essence & Accident in Software Engineering

However, what we can do is at least understand and document a system’s essential complexity. To do so effectively is a tall order for most technologists, since the expression of a system’s essential complexity should include no mention of the underlying technology used in the solution.

The essential elements of a system’s essential complexity definition are the tasks and functions that the system performs, as well as the objects and interactions necessary to perform them. To optimize the cognitive load of such a definition, it is also natural to express this definition as a visual model. Even with visualization, software architects still struggle to keep the elements in their models technology-agnostic and at a consistent level.*

I believe the reason Eric EvansDomain-Driven Design (DDD) methodology has risen to prominence is that it offers a means of visually defining the essential complexity of a software system. In particular, context maps showing domains, subdomains, bounded contexts and their interrelationships come as close as any method I’ve seen to illustrating essential complexity in a useful way. UML certainly intended to provide a means for defining technology-agnostic application descriptions but I believe many of its models naturally bias toward its object-oriented roots. In fact, if you go too deep into the DDD toolbox I think you run into the same bias.**

At this point, I use a derivative of DDD context maps when defining a system of interconnected microservices. I will go into detail on this approach in a future blog post.

A sample context map

Why is it important to understand and document the essential complexity of a software system and what does this have to do with microservices? As microservice systems grow and evolve, much of their benefit comes from the cohesion of the services themselves. Phil Calçado highlights this need in his blog post, “Microservices & the First Law of Distributed Objects”. Cohesion is the product of determining service boundaries, a necessary step in modeling the essential complexity of the system.

Interestingly, harmoniously and seemingly in contradiction to the delineation of complexity described by Brooks, the technology agnostic context map of a microservice system is somewhat isomorphic to the topology of its implementation, much more so than that of an integrated set of monolithic applications. This could be a coincidence or it could be an indication that we’re on to something with this microservice architecture approach.

This blog post is the first in a series. Next up will be a deep dive into context mapping for microservices, followed by an examination of how to sketch the microservice details themselves.

* For a deep dive on the importance of visualization in software architecture, please review the work of Ruth Malan and Simon Brown.

** Simon Brown’s C4 model and Alistair Cockburn’s Hexagonal Architecture offer interesting system visualizations worth investigating, albeit with a different scope than what I am describing.

The Author

Matt McLarty

Team Lead

Matt McLarty is an experienced software architect who leads the API Academy at CA Technologies. He helps organizations with their strategy and architecture for APIs, microservices and enterprise integration. Matt recently co-authored the book Microservice Architecture for O’Reilly, with his API Academy colleagues.

Related Articles


Voltaire, Vonnegut, and the Vocabulary of Microservices

The lack of common concepts and axioms is holding the software engineering industry back. This blog post explores the need for a common distributed systems vocabulary to help with that problem.

Matt McLarty on Aug 10, 2018


Applying and Extending DHARMA

This post gives some practical examples of the DHARMA method for API Security in a Microservice Architecture, and also shares some opportunities for extending the model.

Matt McLarty on Jul 9, 2018

Microservices and APIs
API Strategy

Microservices, APIs and Innovation: The Power of APIs

Explore the role APIs play in empowering teams and enabling organizations to innovate.

Mike Amundsen on May 24, 2018

Join the Conversation