Visualizing Integration Applications

Since I’ve changed roles and started performing architect duties, I have to draw more boxes and arrows than write code. There are ways to fight that, like contributing to open source projects during sleepless nights, POCs, demos, but drawing boxes to express architectures and designs is still big part of it. This post is about visualizing distributed messaging, SOA, microservices applications in agile environments (this term has lost its meaning, but there is not better one in this case). What I like about the software industry in recent years is that the majority of organizations I’ve worked with value the principles behind lean and agile software development methodologies. As long as it is practical, everyone strives to deliver working software (rather than documentation), deliver fast (rather than plan for a long time), eliminate waste, and respond to change. And there are management practices such as scrum and kanban, and technical practices from extreme programming (XP) methodology such as unit testing, pair programing, and other practices such as CI/CD and DevOps to help implement those principles. In this line of thinking, I decided to put together a summary of the design tools and diagrams I find useful in my day to day job while working with distributed systems.

Issues with 4+1 View Model and Death by UML

Every project kicks off with big ambitions, but there is never enough time to do things perfectly, and at the end we have to deliver whatever works. And that is a good thing, it is the way the environment helps us avoid gold plating and supports principles like YAGNI and KISS, so we do just enough and adapt to changes.

Looking back, I can say that most of the diagrams I’ve seen around are inspired by the 4+1 view model of Philippe Kruchten which has logical, development, process and physical views.

4+1 View Model.  From A Practical Guide to Enterprise Architecture by James McGovern, Scott W. Ambler, Michael E. Stevens, James Linn, Vikas Sharan, Elias K. Jo, 2003.

I quite like the ideas and the motivation behind this framework: using separate views and perspectives to address specific set of constraints and targeting the different stakeholders. That is a great way of describing complex software architectures. But I have two issues with using this model for integration applications.

Diagram Applicability

Typically these views are expressed through a unified modeling language (UML), and for each view, you have to use one or more UML diagrams. If I have to use 15 types of UML diagrams to communicate and express a system architecture in an accessible way, it defeats the purpose of UML.

Death by UML
Death by UML. From Wikipedia, derived from a diagram by Paulo Merson.

With such a complexity, the chances are that there are only one or two people in the whole organization who have the tools to create and ability to understand and maintain these diagrams. And having hard-to-interpret, out-of-date diagrams is as useful as having out-of-date documentation. These diagrams are too complex and with limited value, and very quickly they turn into a liability that you have to maintain rather than an asset expressing the state of a constantly changing system.
Another big drawback is that the existing UML diagram types are primarily focused on describing object-oriented architectures rather than pipes and filters architectures. The essence of messaging applications is around interaction styles, routing, and data flow rather than structure. Class, object, component, package, and other diagrams are of less value for describing pipes and filters based processing flows. Behavioral UML diagrams such as activity and sequence get closer, but still cannot express easily concepts such filtering and content based routing, which are a fundamental part of integration applications.

View Applicability

Having a different set of views for a system to address different concerns is a great way of expressing intent. But the existing views of the 4+1 model don’t reflect the way we develop and deploy software nowadays. The idea of that directional flow — that you have a logical view first, which then leads to development and process views, and those lead to a physical view — is not always the case. The systems development life cycle is not following the traditional (waterfall) sequence of requirement gathering, designing, implementing, and maintaining.

Software Development Lifecycle. Derived from an image by Web Serv

Instead other development methodologies such as agile, prototyping, synchronize and stabilize, and spike and stabilize are used too. In addition to the process, the stakeholders are changing too. With practices such as DevOps, developers have to know about the final physical deployment model and the operations team have to know about the application processing flows.

Modern architectures such as microservices affect the views too. Knowing one microservice in a plethora of services is not very useful. Knowing too much about all the services is not practical either. Having the right abstraction level to have a system wide view with just enough details becomes vital.

Practical Visualization for Integration Applications

The closest thing that has been working for me is described by Simon Brown as the C4 model. (You should also get a free copy of Simon’s awesome The Art of Visualising Software Architecture book). In his model, Simon is talking about the importance of a common set of abstractions rather than common notation (such as UML) and then using simple set of diagrams for different level of abstractions: system context, container, componentand class. I quite like this “outside-in” approach, where you first have 10000 foot view and with each next level, going deeper with more detailed views.
C4 is also not an exact match for middleware/integration applications either, but it is getting closer. If we were to use the C4 model, then the system context diagram would be one box that says ESB (or middleware, MOM, or microservices) with tens of arrows from north to south. Not very useful. The container diagram is quite close, but the term container is so overloaded (VM, application container, docker container) which makes it less useful for communication. Component and class diagrams are also not a good fit as pipes and filter architectures are focused around enterprise integration patterns, rather than classes and packages.
So at the end, what is it that worked for me? It is the following three types of diagrams which abbreviate as SSD (not as cool as C4):  system context, service design, and deployment.

System Context Diagram

The aim of this model is to show all the services (whether they are SOA or microservices) with their inputs and outputs, ideally having the external systems on the north, the services in the middle section, and internal services in the south. Or you could use both external and internal services on both side of the middleware layer as shown below. Also having the protocol (such as HTTP, JMS, file) on the arrows, with the data format (XML, JSON, CSV) gives useful context too, but it is not mandatory. If there are too many services, you can leave the protocol and the data format for the service level diagrams. I use the direction of the arrow to indicate which service is initiating the call rather than the data flow direction.

System Context Diagram
System Context Diagram

Having such a diagram gives a good overview of the scope of a distributed system. We can see all the services, the internal and external dependencies, the types of interaction (with protocol and data format), and the call initiator.

Service Design Diagram

The aim of this diagram is to show what is going on in each box representing a middleware service from the system context diagram. And the best diagram for this is to use EIP icons and connect those as message flows. A service may have a number of flows, support a number of protocols, implement real time, or batch behaviour.

Service Design Diagram
Service Design Diagram

At this level, we want to show all possible data flows implemented by a specific service, from any source to any destination.

Deployment Diagram

The previous two diagrams are the logical views of the system as a whole and each service separately. With the deployment diagram, we want to show where each service is going to be deployed. Maybe there will be multiple instances of the same service running on multiple hosts. Maybe some services will be active on one host, and passive on the other. Maybe there will be a load balancer fronting the services.

Deployment Diagram
Deployment Diagram

The deployment diagram is supposed to show how individual services and the system as a whole relates to the host systems (regardless whether that is physical or virtual).

What Tools Do I Use?

The system context and the deployment diagrams are composed only of boxes and arrows and do not require any special tools. For the service design diagram, you will need a tool that has the enterprise integration pattern icons installed. So far, I have seen the following tools with EIP icon support:

Other development tools that could be also used for creating EIP diagrams are:

A system context diagram is useful to show the system wide scope and reach of the services, a service design diagram is good for describing what a service does, and a deployment diagram is useful mapping all that into something physical.

In IT, we can expand work and fill up all the available time with things to do. I’m sure given more time, we can invent ten more useful views. But without those basic three, I cannot imagine describing an integration application. As Antoine de Saint-Exupery put it long ago: “Perfection is finally attained not when there is no longer anything to add but when there is no longer anything to take away.