OMG are you still using Rational Rose?

Recently, I wrote the first in a series of articles about how to understand and document an architecture. One amusing comment on the post was “OMG are you still using Rational Rose?”. The answer is, of course, no. I’m actually using PlantUML.

The original goal of this article was to simply explain why I use PlantUML. But it’s expanded to cover the following topics:

• Architecture is elements and relations
• Architecture is multi-dimensional
• Architecture documentation != diagrams
• Documenting dynamic behavior is essential
• Why UML and PlantUML?
• Use the visual notation and tooling that works for you

Architecture is elements and relations

Len Bass and colleagues at the Software Engineering Institute define software architecture as follows:

The software architecture of a computing system is the set of structures needed to reason about the system, which comprise software elements, relations among them, and properties of both.

Superficially, it sounds like an architecture is a collection of boxes and lines 😀. But in reality, it’s a complex multi-dimensional model.

Architecture is multi-dimensional

Of course, an application’s architecture is a bit more complicated than that. Architecture is multi-dimensional and is described by a set of views, each of which is a collection of elements, relations and their properties.

For example, as I discuss in Using scenarios to reinvigorate your microservice architecture I like to use the following views to document an architecture:

• System context - the black box model of the application.
• Logical - consists of elements, such as classes and packages, and the relations between them, such as class X is subclass of Y and class X is part of package Y
• Implementation - consists of elements, such as modules (e.g. JAR files) and components (e.g. executable JAR files), and the relations between them such as module X is part of component Y
• Deployment - consists of infrastructure and cloud resources, such as Kubernetes deployments, pods, etc, and AWS resources, such RDS instances.
• Repository/Deployment pipeline - the elements that comprise the code repositories and the deployment pipeline

Architecture documentation != diagrams

There’s a tendency to think that architecture documentation is merely a collection of diagrams. In reality a view’s documentation is some combination of diagrams and text. And, in some cases, it might be purely textual. The goal is communicate the view’s model clearly.

For example, here’s the textual description of the FTGO application’s system context:

The explanation typically describes each element and relation. It might also provide a rationale for the design, e.g. an architecture decision record.

Documenting dynamic behavior is essential

It’s insufficient to merely describe a view’s static structure. You must describe a view’s dynamic behavior, which is how its elements collaborate during a scenario. This is the +1 of the famous 4+1 view model of architecture. Since the scenarios are derived from user stories, documenting the dynamic behavior using scenarios connects the architectural elements to the requirements. A continuation of the outside-in, user-goal focussed approach to software architecture documentation.

For example, a key user story in the FTGO application is Place Order. This user story has one or more key scenarios. These scenarios would most likely be part of the documentation for the system context, logical, implementation and deployment views. The system context documentation would describe how the consumer (actor), the FTGO application, and the external services would collaborate to create an order. Similarly, the logical view’s documentation would describe how the classes collaborate. Later articles in the series, will describe how document diagram behavior in more detail.

Why UML?

Now that I’ve discussed how application’s architecture is described by a set of views, each of which consists of diagrams and/or text, I can now talk about UML. An architecture diagram must clearly communicate what types of the elements and relations that it depicts. Otherwise, there is a danger that a diagram is a confusing collection of boxes and lines, A good way to provide clarity is to use a ‘standardized’ notation, which is why I use a subset of UML. Also, it’s often helpful if a diagram also has legend.

Why PlantUML?

There are a few different ways to create a UML-based architecture diagram:

• Specialized UML tools, such as Rational Rose
• General purpose drawing tools, such as Omnigraffle
• Text-based diagram generator, such as PlantUML and Mermaid

These days I primarily use PlantUML. While it might not produce the most beautiful diagrams, PlantUML makes creating diagrams quick and easy. And, since it’s text based, the diagram files can be stored in Git.

For example, I defined this diagram:

using the following PlantUML file ftgo-system-context.txt:

@startuml
hide empty members

left to right direction

component FTGO_Application
component Twilio
component Stripe
component AWS_SES

actor Courier
actor Consumer
actor Restaurant

Courier --> FTGO_Application
Consumer --> FTGO_Application
Restaurant --> FTGO_Application

FTGO_Application --> Twilio
FTGO_Application --> AWS_SES
FTGO_Application --> Stripe

@enduml

Creating images from PlantUML files

You can easily embed a PlantUML diagram in an AsciiDoc document by using Asciidoctor Diagram:

plantuml::./ftgo-system-context.txt[]

Given that architecture documentation is more than just diagrams, I find this Asciidoctor integration especially useful.

Alternatively, you can create an image file by running PlantUML directly. For example, I’ve packaged PlantUML and its dependencies as a Docker image.

PlantUML also has many other integrations. See the PlantUML website the details.

Use the visual notation and tooling that works for you

I’ve described why I use UML and PlantUML. But there are lots of other options. You should use whatever works for you.

It’s important to remember, however, that:

• Architecture is elements and relations
• Architecture is multi-dimensional
• Architecture documentation != diagrams
• Documenting dynamic behavior is essential

Need help adopting microservices?

I provide consulting and training.