The Problem with Platform-Specific Architecture Diagrams

The emergence of cloud architecture has spawned some new and trending platform-specific solution architecture diagrams. I like innovation just as much as the next architect. Still, platform-specific notations always give me pause, and not only because I have found the Unified Modeling Language (UML) so well suited for solution architecture diagrams. I am going to share the problems with platform-specific diagrams as well as when it is appropriate for architects to use them.

What are Platform-Specific Architecture Diagrams?

First, I'll provide some examples of what I mean when I say "Platform-Specific Architecture Diagrams." Here are a few current (and prevalent) ones:

AWS Architecture Diagrams

You can find the icons and examples here: https://aws.amazon.com/architecture/icons/

Azure Architecture Diagrams

You can find the icons and examples here: https://docs.microsoft.com/en-us/azure/architecture/icons/

Google Cloud

You can find the icons and examples here: https://cloud.google.com/icons

Cisco Networks

(I included this, lest you think cloud services are the only offender in town.)

You can find the icons and examples here: https://www.cisco.com/c/en/us/about/brand-center/network-topology-icons.html

In these examples and others, the vendor provides diagram icons and either explicit usage instructions or samples that imply usage. In addition, a host of tools "ride the wave" and add support for the new platform-specific architecture diagram notation. The acolytes then line up and start spreading the icons!

What is the Problem?

On the surface, fit-for-purpose icons seem like an idea I would get behind. So what is my problem with them?

Trends are Fleeting. Architecture is Eternal. I don't want to sound like a curmudgeon, but today's architecture trend is tomorrow's legacy system. (ps. I want the time I spent learning Novell icons back.) A solution architect needs to keep pace with new architecture paradigms, but learning new platform-specific architecture diagrams and icons to communicate them is not a valuable use of time. Solution architects should burn a diagram notation into muscle memory until they can use it to fluently communicate architecture. At that point, the notation should get as much thought as the keyboard does when you are writing a document.

Architecture is Heterogeneous. Solution architects assembly solutions from the technology building blocks of the enterprise. In any enterprise of moderate complexity, those building blocks are a variety of technologies and some are, er, more mature than others. This diversification of technologies results in architectures with an expansive sprawl across platforms and paradigms. For example, a single architecture can include AWS and Azure cloud components alongside on-premises mainframe and distributed components.

Architecture is already Confusing Enough. The goal of architecture diagrams is to communicate architecture designs clearly. The most optimized approach is to teach your audience how to read a single, simple diagram approach, then let them enjoy that forever. The last thing you want is for them to have to figure out your icons and notation before they can start understanding your architecture.

You are an Architect, not a Salesperson. Those icons spread the brand all over the place; they are as much a marketing tool as an architecture tool. Plus, any time someone new gets hired in the marketing department, new and improved icons are released. The impact can range from making your diagram look dated to obsoleting the meaning of the icons you used.

What is the Solution?

Not surprisingly, we recommend you adopt a platform-agnostic standard notation for solution architecture diagrams. Our recommendation is the tried and true UML.

1. The icon-free shapes are a boring but timeless, and can represent any architecture component you throw at them. With them you can seamlessly diagram your way across all architecture paradigms and components, including ones you need a time machine to purchase.
   
2. In a pinch, you can add icons to the components - UML allows that - to satisfy your trendy, flavor of the day, icon-architecture audience, thus making UML your rosetta stone across icon architecture boundaries. So not only can UML be your diagramming solution, but it can also be the foundation of a hybrid solution.

If UML is not your preference for Solution Architecture diagrams, then select the notation of your choice, but make sure it is platform-agnostic! I would also recommend against too many icons, but I will save that for another article!

When to use Platform-Specific Architecture Diagrams

There are situations where platform-specific architecture diagrams make sense.

1. Platform-specific diagrams can be appropriate at the more detailed levels of the architecture where the application and component architecture are designed. While solution architects assemble a solution using the technology building blocks of the enterprise, those building blocks often require design as well. Often times a fit-for-purpose design product, including a specific diagramming approach, is best suited to communicate that level of design to the developers and/or implementation team.
   
2. In organization's where the entire technology stack is standardized on a single platform (or platform vendor), a platform-specific architecture diagram approach that is well suited for the organization's architecture design needs may be suitable. Even then, this will not provide the greatest design agility moving forward if the organization decides to take advantage of future innovations outside the current stack.
   
3. In low-code and other graphical configuration-over-code environments, icon-based workflows often serve as both code and visual documentation (aka. diagrams). This is a special case of #1 because these diagrams are usually created at the building block level. In this case a "comes with" diagram can be very fit-for-purpose.
   
   There are also tools for some platforms that generate platform-specific architecture diagrams based on the configured operating environment. Magic diagram creation seems like a no brainer: why not just press a button to get a diagram? However, this would only work in the same scenarios as #2. Even then, a generated diagram many not be at the correct logical solution level nor apply the proper lens to the diagram for the solution architect's specific need.

Fit for Purpose Architecture Diagrams

The lesson here is to pick the right tool for the job.

For solution architecture diagrams that assemble solutions from the technology building blocks of your enterprise, use a platform-agnostic standard notation. That notation will handle all the systems and architecture paradigms in your organization and gain efficiency over time as it becomes fluently spoken in your organization. UML is my "go-to" for most solution views, like Information Flows, but we have adopted other standard notations when appropriate, like Solution User Diagrams.

For more detailed component-level architecture or in single-platform technology environments, leverage a fit-for-purpose diagram method and icons that are more tightly coupled with the platform architecture you design.

The most important thought I can leave you to document your design regardless of what approach you take!