The Art of Visualising Software Architecture

Ask somebody in the building industry to visually communicate the architecture of a building and you'll be presented with site plans, floor plans, elevation views, cross-section views and detail drawings. In contrast, ask a software developer to communicate the software architecture of a software system using diagrams and you'll likely get a confused mess of boxes and lines. Simon Brown has asked thousands of software developers to do just this over the past decade and continues to do so today. The results from these software architecture sketching workshops are still surprising, anecdotally suggesting that effective visual communication of software architecture is a skill that's sorely lacking in the software development industry.

Of course, as an industry, we do have the Unified Modeling Language (UML), but asking whether this provides an effective way to communicate software architecture is often irrelevant because many teams have already thrown out UML in favour of much simpler "boxes and lines" diagrams. Abandoning UML is one thing but, perhaps in the race for agility, many software development teams have lost the ability to communicate visually.


This is a recording of Simon Brown's keynote at the nCrafts conference in Paris, France during May 2016. This talk explores the visual communication of software architecture based upon his experience of working with software development teams across the globe. It looks at what is commonplace today, the importance of creating a shared vocabulary, diagram notation, the value of creating a model plus how to use tooling and static analysis techniques to automate diagram generation.

Software Architecture for Developers: Volumes 1 & 2

This is Simon Brown's Software Architecture for Developers (Volume 2) ebook, which is available on Leanpub. It's a short guide to creating a shared vocabulary and simple software architecture diagrams using the C4 software architecture model.

Simple Sketches for Diagramming Your Software Architecture

This is a short article written for Voxxed that summarises the C4 model.

Here are some tips for drawing software architecture diagrams, using the C4 model as a starting point. They're useful regardless of whether you're using a whiteboard, a general purpose diagramming tool or Structurizr.

1. Create a ubiquitous language

Within your team, agree upon some terminology to think about and describe the static structure of your software system. For example, here is a simple hierarchical approach that defines 4 levels of abstraction:

A software system is made up of one or more containers (web applications, mobile apps, standalone applications, databases, file systems, etc), each of which contains one or more components, which in turn are implemented by one or more classes.

Use this as a starting point and adjust it if you're not using an object-oriented programming language. For example, perhaps "components" becomes "modules", and "classes" becomes "objects" or "functions".

2. Draw some diagrams

Draw some diagrams to visualise each level of abstraction separately. The C4 model defines 4 levels of static structure diagrams: System Context, Containers, Components and Classes (or Code).

System Context diagram

1. System Context diagram

Container diagram

2. Container diagram

Component diagram

3. Component diagram

Feel free to consider diagrams showing the classes (or code) as optional, as they will likely show too much detail. Of course, there may be situations when you want to show component implementation details, and a UML class diagram is a good way to do this.

Add more diagrams as needed

Add more diagrams to describe other aspects of your software system as necessary. For example, sequence/collaboration diagrams showing how components collaborate at runtime to implement a user story, a deployment diagram to show the mapping from containers to infrastructure, a domain model, etc.

3. Boxes

Agree upon a notation to represent each of the elements defined in the static structure of your software system. Adding some descriptive text to the boxes is a great way to reduce ambiguity while creating a simple "at a glance" view, especially if that text summarises the element's responsibilities.

Person
Box
Cylinder

4. Lines

Again, agree upon a notation for your lines too. A simple way to avoid confusion is to make all arrows unidirectional, so they only point one way. Whether the arrows represent dependency/uses relationships or data flows is your choice. Add some descriptive text to explain the intent and direction of the relationship.

Relationship
Relationship

5. Titles

Put a title on every diagram, so that the reader knows what the scope of the diagram is and what to expect.

6. Acronyms

Be wary of using acronyms, especially those related to the business or domain that you work in.

7. Key

Make your diagram self-describing by ensuring that all notation you use (shapes, colours, line styles, etc) is defined on a diagram key.

8. Reality

Finally, make sure that your diagrams reflect the reality of what you're going to build, or what the code actually looks like.