By Dan Hughes, of Wittij Consulting

Diagrams are a powerful tool for solution architecture design. Firstly, a solution architect can use them to effectively think through an architecture design because the diagrams help to structure thinking and because the architect can put the diagram down and come back to it later with a “fresh set of eyes.” Secondly, a solution architect can use the diagrams to effectively facilitate the conversations required to share the design, gather feedback, and gain approval. Finally, the diagram becomes a historical record of the architecture (even a dated design is better than no design).

After decades of designing solution architectures, I have landed on a set of views that I use to depict any solution architecture. You will note that I said diagrams and not a diagram. While it seems counter-intuitive, using multiple fit-for-purpose views is more understandable than trying to jam everything onto a single diagram. Without further ado, here are the four views I recommend.

The User View

Nobody designs technology solutions in a vacuum. All technology solutions are designed to address people’s needs: all architecture is people-centric. Therefore, the first and most critical view for describing an architecture is one that clarifies who is using the solution and what they are using it for. Knowing who and what is usually enough for an architect to design a solution without having detailed requirements. Many diagrams notations can depict who and what, like a system context diagram or UML use case, but I prefer using a solution user diagram.

A solution user diagram is simple; it is barely a diagram. So, people can understand it or even create one with little or no training or prior experience. You create “user cards” with roles and list architecturally significant use cases on the cards. You can make it in just about any tool you can use to write words, enabling just about anybody to create one. Finally, while it starts simple, you can layer additional dimensions using colors, fonts, and grouping boxes.

Although we are discussing this view in the context of solution architecture, I have frequently used it to confirm the scope across a group of stakeholders even when no technical solution is in play for projects and business process initiatives.

The Conceptual Architecture View

Enter stage left… Powerpoint! All solution architects must be prepared to present proposed architectures to a broad audience, from engineering to executive management. They need a conceptual depiction of the solution architecture that is accurate enough to ensure everyone is on the same page but pretty enough for a presentation. You can draw a conceptual architecture using any “boxes and lines” notation, but I am a big fan of a level of standardization around diagrams. It drives consistency for the viewers, and rules help diagram creators know when they have the correct information on the page. I have adopted a user-centric, tiered approach for a Conceptual Solution Architecture diagram for many years.

By making the users the focus of a conceptual view, you ensure that people remain front and center for your architecture. The users also tie the conceptual architecture to the solution user perspective above. Regardless of what notation you land on for conceptual solution architecture views, I recommend keeping it very high level and abstract and trading off accuracy and completeness for clarity.

The Information Flow

Capturing the flow of information is a popular and effective approach for understanding a solution architecture, so many notations exist for doing this (e.g., DFD, IDEF0). In addition, countless versions of data flow diagrams that don’t use standard notation exist. It is an intuitive way to contemplate solution architecture, so it is often a “go-to” for experienced and aspiring architects.

I prefer the UML information flow notation to capture information flows. It cleanly captures the essential elements of a data flow diagram:  the components exchanging information, the direction of the information exchange, and a business-level description of the information exchanged. It is a powerful view that can zoom up and down to cover everything from enterprise systems to low-level components.

I highly recommend including the business description of the information flow on the lines. It is the item I most often see omitted, yet when present, it makes the diagram much more helpful.

Logical Component Diagram

A component diagram is the most technical and detailed of the diagrams I create for solution architectures. I use it to depict the logical components of an architecture. It identifies the architecturally significant elements of the architecture and how they connect. I find a UML Component diagram to be highly effective for this purpose.

You should stick to only the basic notation to keep it simple. UML provides a suitable notation to capture the components, indicate what interfaces each component offers, and identify what other components are using those interfaces. The rigorous rules also help a solution architect ask the right questions when documenting an existing solution architecture or designing a new one. A precise notation helps you know when you are done with a diagram (beyond “whenever you stop diagramming”).

Getting Started

If you haven’t done much formal architecture diagramming, or even much architecture diagramming at all, there will be a learning curve to get up to speed. Trust me when I say that it is worth the effort. Time and time again, I find this set of diagrams indispensable to untangle existing solution architectures and design new ones. I will leave you with a few thoughts as you continue or start your architecture diagramming journey:

1. Don’t get distracted by the tool. It doesn’t matter what software you use; you can even choose to use a whiteboard or graph paper.
2. If you are using a repository-based modeling tool, be careful. The key to architecture diagrams is that you are always using them to communicate something; you rarely use them to communicate everything. So, while it is great to have everything in your architecture repository, that doesn’t mean it should all be on your diagram: choose clarity over completeness.
3. Just diagram. A diagram is a tool, not an output. Don’t interview and take notes until you think you are ready to diagram. Use the diagram iteratively to collect information, collaborate, and think.

Happy diagramming!