How architecture diagrams enable better conversations

Earlier this year myself and a couple others at DrDoctor did some training in C4 Architecture modelling¹. The trainer was really good and over a few sessions with him we got the hang of the method. We went onto use what we had learnt, meeting everything Thursday over the course of 3 months. We focused mainly on modelling our existing architecture into Level 1 (Context) and Level 2 (Container) diagrams. This process was enlightening and we all learnt a lot from it - that alone could easily be a couple of posts.

I have had two main takeaways:

• From the training itself, is that the C4 method provides a consistent language which can be used when talking about architecture
• From using and applying the C4 method, is that diagrams can be an enabler for better conversations

Before digging into the benefits that come from having C4 diagrams, there are two limitations in particular that I would like to highlight.

1. The C4 Model does not provide a standard way of communicating the story of your architecture in written form. Given all the things it does well, provides consistent language, introduce detail/complexity incrementally through different levels of diagrams, this felt like an oversight and something that would be really useful to have.

2. The lack of real-world examples available - this obviously isn’t a limitation of the model itself but rather due to the fact that companies don’t want to advertise their architecture in detail in public. However it does mean that understanding how to practically apply the model outside of the public examples available is difficult.

We had a number of sessions with Brian from buildingbetterteams.de, he was able to walk us through the basics and then guide us through the process of modelling our existing architecture (company money well spent).

Situations where diagrams have been an enabler

Onboarding new team members

You can imagine when onboarding new engineers to a team the conversation goes something like this

1. git clone /path/to/repository
2. open in [your IDE of choice]
3. why haven’t you finished your first story/task/ticket yet?

(Thankfully this isn’t how we do onboarding at DrDoctor). One of the things that is missing from the above, one of the many things missing, is context. Even if you follow “best practices” around Clean/Hexagonal/DDD layout for your code/solution, it’s still confusing. Questions will still need to be asked and answered:

• What is the main entry point?
• What are (if any) the interactions between projects?
• What external dependencies are there?
• Do any external projects depend on this solution?

This is where having C4 architecture docs has come in handy, they have served as a starting point for helping new engineers build up their mental model of the architecture, interactions and dependencies of new projects.

It’s worth adding, that the diagrams I’ve been using with my team have been useful not only for new engineers but also for our Engineering Manager and Technical Product Manager - specially to help them understand the complexity of the project that we’re working in, and to understand why some piece of work are more complicated than others.

Planning upcoming work

As a team we have recently been preparing to build out a new piece of major functionality for an existing system. Understanding the what of the functionality was straightforward enough. But to get to the how was enabled by having a decent (ie pretty good/good enough) architecture diagram. The architecture diagrams were useful as prompts for conversation.

The diagrams gave all team members something to centre around, it also gave everyone common language to use.

They also helped us to think about iterative ways to deliver the end goal. Being able to visualise the end state of what we wanted to deliver helped us think about how we could do this incrementally. If we had only spoken about this verbally I don’t think we would have or could have, come to the same conclusions about how we wanted to go about building this.

Communicating changes to other teams

Following on from the previous point, this new piece of functionality that we’re setting out ot build involves making some changes to the larger architectural landscape at DrDoctor. Which means that we are going to be making changes to how some projects which are owned by other teams function. Having architecture diagrams to communicate the scope of change to other Leads has been a game changer. Once again, the diagrams were useful as the centre piece of conversations and helped others outside our team to build up a mental model of what we were setting out to change.

I was also able to easily talk though the iterations we would be going through to deliver the end state.

Wrapping up

I still feel like I’m early in my journey of building (or drawing) architecture diagrams, however based on recent experiences I can see the immense value they bring to an engineering team. These benefits reinforce that the time and effort put into creating and maintaining architecture diagrams is time well spent.

• Focuses communication: Having a diagram to centre conversations around has been a game changer, the focus is taken off an individual and put on something that can be reasoned about, questioned, probed without it feeling personal
• Universal understanding: Diagrams being visual in nature help technical and non-technical folks to understand the interaction points and dependencies. They also provide common language for all team members to use.
• Facilitates planning: Having diagrams has been incredibly helpful during the planning process (of big and small pieces of functionality) particularly when a team consists of a number of new team members, being able to refer to components and understand the scope of change that a piece of functionality will have helps the team to understand the complexity of the change