application architecture   architecture documentation   architecting  

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 tendancy 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:

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


Creating images from PlantUML files

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


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.

application architecture   architecture documentation   architecting  

Copyright © 2023 Chris Richardson • All rights reserved • Supported by Kong.

About is brought to you by Chris Richardson. Experienced software architect, author of POJOs in Action, the creator of the original, and the author of Microservices patterns.

Chris helps clients around the world adopt the microservice architecture through consulting engagements, and training workshops.

Learn how to create a service template and microservice chassis

Take a look at my Manning LiveProject that teaches you how to develop a service template and microservice chassis.

New virtual bootcamp: Distributed data patterns in a microservice architecture

My virtual bootcamp, distributed data patterns in a microservice architecture, is now open for enrollment!

It covers the key distributed data management patterns including Saga, API Composition, and CQRS.

It consists of video lectures, code labs, and a weekly ask-me-anything video conference repeated in multiple timezones.

The regular price is $395/person but use coupon JUNVCEJE to sign up for $195 (valid until February 1st, 2023). There are deeper discounts for buying multiple seats.

Learn more

Signup for the newsletter

LEARN about microservices

Chris offers numerous resources for learning the microservice architecture.

Training classes

Chris teaches comprehensive workshops, training classes and bootcamps for executives, architects and developers to help your organization use microservices effectively.

Avoid the pitfalls of adopting microservices and learn essential topics, such as service decomposition and design and how to refactor a monolith to microservices.

Delivered in-person and remotely.

Get the book: Microservices Patterns

Read Chris Richardson's book:

Example microservices applications

Want to see an example? Check out Chris Richardson's example applications. See code

BUILD microservices

Ready to start using the microservice architecture?

Consulting services

Engage Chris to create a microservices adoption roadmap and help you define your microservice architecture,

The Eventuate platform

Use the platform to tackle distributed data management challenges in your microservices architecture.

Eventuate is Chris's latest startup. It makes it easy to use the Saga pattern to manage transactions and the CQRS pattern to implement queries.

ASSESS your architecture

Assess your application's microservice architecture and identify what needs to be improved.

Consulting services

Engage Chris to conduct an architectural assessment.

Join the microservices google group


Note: tagging is work-in-process

anti-patterns   ·  application api   ·  application architecture   ·  architecting   ·  architecture documentation   ·  dark energy and dark matter   ·  deployment   ·  development   ·  devops   ·  docker   ·  implementing commands   ·  implementing queries   ·  inter-service communication   ·  loose coupling   ·  microservice architecture   ·  microservice chassis   ·  microservices adoption   ·  microservicesio updates   ·  multi-architecture docker images   ·  observability   ·  pattern   ·  refactoring to microservices   ·  resilience   ·  sagas   ·  security   ·  service api   ·  service collaboration   ·  service design   ·  service discovery   ·  service granularity   ·  service template   ·  software delivery metrics   ·  success triangle   ·  team topologies   ·  transaction management   ·  transactional messaging

All content


24 Jul 2017 » Revised data patterns