The Architecture Heat Map

Communicating your progress and plan of action for a software project to business people is important because it enables them to coordinate other aspects of the project like marketing, hiring, or parties.



If you don’t provide enough transparency, you might undo all the hard work of creating great software by costing the business time and money. As a tech lead, your reputation is definitely at stake.





A strategy I’m using on a current project, with thanks to the ingenuity of my colleagues, involves architectural diagrams of the system in combination with colour codes to express how developed each part of the system is.



It worked so well that the clients explained to us how we would be delivering the application, just by looking at the diagram, before we even had chance to explain it to them.

Before I show you the diagram, let me explain the situation a little

Our goal for the client to is to re-develop their ageing online leads-generation service, into a modern, reactive, best-in-class offering that will make users happy and the company more money.



There are two aspects that are significant — technical unknowns and domain unknowns.



Their existing solution lacks a number of concepts that are present in the real-world domain — relating to the searches users would like to make and the content they are offered. We know they’re missing because other sites expose these concepts and users are making full use of them.

Importantly, then, we need to spend a significant amount of time learning, and continuing to learn about the domain we are operating in.



Additionally, the current application is C#, .NET & Windows all the way down. For the reactive system we’re building, this choice of technology is inadequate, plus has lots of licensing costs that we can avoid by using open source alternatives.



Critically, then, we also need to understand some of the technologies that we’ll be using before we start to build the application. It’s too risky for us to leave significant choices to a late stage.

How the heat map diagram helps

Because of the unknowns mentioned above, we decided to spend some time up-front learning about the domain and the technology choices. This was achieved by building a prototype.



To communicate this to client we showed them the architecture heat map where half was a light-green, and the other half was grey. Green means simplest possible thing to give us the level of feedback we need. Grey means preliminary research but yet to be incorporated into the prototype.



I said to the client we would be spending time in each area to identify domain and technical risks. They then immediately said “so in a few weeks the diagram we will be a map of green”. I was quite chuffed that the diagram worked exactly as intended.



Here’s what the diagram looked like at the time of that conversation….

Click on image to see full-size

As each week passes both business people and technical people can see the level of progress being made. It’s a useful communication tool that helps to keep everyone synchronised, especially in a distributed team.

If some people expect the system to be in a more developed state, or certain features to have been delivered before others, this diagram will sometimes kick start those conversations if it hasn’t helped to prevent them.

Choosing the right diagram to use

As a fan of Simon Brown’s C4 diagramming wizardry, for the architecture heat map I chose a component diagram that shows high-level use cases flowing right through the application.



The important reason I chose this diagram was that it shows domain terminology — we want the client to understand it. Another crucial reason is that by mapping requirements to components in the system, it’s easy to build up a picture of what stage each requirement is at..



Choosing a colour code that’s relevant to your context

On our project we started from a grey — meaning we are aware of this part of the system and the requirements it is going to satisfy, but are yet to implement. We then had green, meaning we’ve incorporated a minimal amount of logic into the prototype to de-risk this part of the system, but it’s far from production quality.



It has a few other levels of heat culminating in a dark orange that says “up to-date with requirements and deployed”. This is also important, because the client knows to not expect any more work in this area. This gives them an opportunity to come to us with next round of suggestions and improvements instead of thinking there is more to come.

These are all based on how we decided we would like to carry out this project, best in-line with the constraints we were dealing with it.

Have a nice day.