The State of Integration Diagram

Or how to create a visual that allows you to see the work in progress and risks of a complex system in a single glance.


In 2009, I was the technical lead of a small team at a digital agency in London called AKQA. I joined the team when they were in the middle of building an app for Nike called True City.

The app went on to receive a few awards and held the number one spot on the Apple app store for a time. It brings me great joy to watch the trailer video below after 13 years because this project was a ton of fun!

Nike True City App Trailer

The app is fairly simple by today's standards. You have a Google map view which shows you content curated by influencers for points of interest. It also shows product drops on the map with a countdown, as well as gives users the ability to read QR codes from around the city.

The tech team I was to lead was comprised of an iOS developer, a backend Java developer, and a feisty QA named Vince. And as always with these kinds of projects, we had just 8 weeks to launch.

When I asked to see the app, I was first shown the UX diagrams, then I was directed to the iOS developer who showed me the app on his local machine, and the backend guy who showed me some data in a database.

So we had some UX documentation, an app shell, and some data, but nothing tangible that was tested by Vince or seen by the client. I got the sense that we were in a bit of trouble!

In order to get control and a better sense of progress, I needed a way to visualize what had been done so far, what remained to be done, and to help reduce the risk of delivering a client project.

Although I was very familiar with Java, I was completely clueless when it came to Swift on iOS. But I knew from experience that when you look beyond syntax, code is just a set of modules that interact with one another. So I thought, why not use these modules as a way to visualize progress?

I started by having one-on-one sessions with the devs and asked them to walk me through the code as I drew boxes to represent the modules. I also drew lines between modules that had a dependency on one another. And on those lines, I wrote the structure of any message being exchanged between said modules.

The result was something that looked like this (I don't have the original so this is a mock version that illustrates the point)

The State of Integration diagram evolution showing modules and connections between them

The app design was simple. The team designed it as follows:

  • A file filled with Points of Interest (PoI's) is uploaded to an FTP server
  • A backend importer process places those PoI's in a MySQL database
  • The app queries those PoI's over HTTP and displays them on a map
  • There are some fancy UI functions such as sharing
  • There is some notifications functionality

Once I had a view of the modules, I then started to ask what was done, what is in progress, and not started. The definition of done here means on the live site. I considered anything that wasn't on the production site technically still in progress.

So I ended up with this initial illustration:

The State of Integration diagram evolution showing the progress of each module through color

Red = Not started | Blue = In Progress | Green = Done

I then wanted to know the answer to one of the most important questions - what has been integrated so far – in other words – what is the "state of integration?"

So I color coded the lines between the modules using the same scheme as above, which led to this rendition:

The State of Integration diagram evolution showing the progress of each connection between the modules through color

Now things got really interesting. The risk of any system is typically in its integrations, and those can be within a team or to external systems. In this instance, the front-end was not talking to the backend, and the backend was not wired up to external systems.

So we got to work. I asked the team to stop working on the modules within their respective subsystems, and instead to focus on getting a small slice of integration between all the pieces on production-ready infrastructure.

As we didn't have production-ready infrastructure, I put my devops hat on and drew out what it would take to get this app into production. We got a diagram that looked something like this:

The State of Integration diagram evolution showing the addition of the CI/CD Pipelines

There! I could see where we were and how much was left. I could estimate at a glance that we were about 2% green or "done" and 10% blue or "in progress".

I made sure to have this diagram visible by using as the central talking point on our daily standup meetings, as well as status reports to the higher ups. And through a process of divide and conquer, we ended up with a diagram progression that is illustrated in the animation below:

The State of Integration diagram animation showing color-coded progress over time

This turned out to be a practical way of getting the team to own the problem of integrating early and often, and the visualization had a gamification aspect. The team rallied to make the lines go green and gained momentum in reducing risk by completing the integration between modules.

Even the execs took interest in coming to look at this diagram on a regular basis in order to get a read on where things are at. While they didn't really understand the details within each module, they could easily read the red/blue/green color coding, and they could see the progress the team was making day in, day out.

Fast forward 13 years and I've used this technique with great success to manage projects of all sizes, ranging from the 2-person dev team, to a 9-team project distributed across multiple time zones! It scales very well.

I've learned much along the way about do's and don'ts of this technique. Some key lessons are:

  • Make it visible and use it at regular meetings like daily status, planning, etc.
  • Keep it up to date and living even if you have to personally own this task
  • Engage everyone involved and make sure they own their part
  • Draw modules at a "working chunk" level such as 0.5 - 2 sprints of work
  • Draw every single known integration to visualize the risks
  • Strive for an a-cyclical symmetrical structure to spot architecture issues
  • Be consistent and diligent with status definitions like "Done"

I can’t stress enough how much control over a project the State of Integration Diagram technique gives to all the parties involved. Everyone has a clear picture of where they are and where they need to get to. This clarity contributes to a strong sense of confidence, responsibility and purpose, which ultimately leads to smoother collaboration.

I hope this will inspire you to incorporate the State of Integration Diagram technique into your own practice to deliver higher software quality, faster. I’m always curious how this works out for other people so please don’t hesitate to get in touch with me to discuss!

Let me know if you have any questions or thoughts in the comments below.


Let us help you on your journey to Quality Faster

We at Xolvio specialize in helping our clients get more for less. We can get you to the holy grail of continuous deployment where every commit can go to production — and yes, even for large enterprises.

Feel free to schedule a call or send us a message below to see how we can help.

User icon
Envelope icon

or

Book a call
+
Loading Calendly widget...
  • Apollo GraphQL and Xolvio introduce supergraph professional services

    Announcing our official partnership with Apollo GraphQL to help companies scale their supergraphs.

  • Digital Acceleration: The Single Biggest Business Benefit of GraphQL

    Or how to pitch GraphQL adoption to your leaders whether they are developers or not.

  • The real story behind Apollo GraphQL

    An interview with Apollo CEO, Geoff Schmidt, diving deeper into the origins of the supergraph.