I believe most developers and architects know about and have worked with sequence diagrams. Between Use case diagrams, Class diagrams and Sequence diagrams, I think Sequence diagrams are the most used of the three, in some form. There are fortunately fewer elephants in the room to address with the Sequence diagram.

What are Sequence diagrams?

In case you are in doubt about the purpose and usefulness of Sequence diagrams, let me share with you a personal anecdote on the power of the Sequence diagram. I have chosen this example because it exemplifies a type of communication issue I see happening again and again. In summary, it was a simple sequence diagram that uncovered a potentially costly assumption that persisted for over six months in a big project I once worked on. Given the circumstances, I would say uncovering this during the early stage of the project saved it from being delayed. If you are interested in avoiding such problems, I urge you to continue reading.

Before you read any further I suggest that you read my article on Use Case diagrams, as I will make use of this type of diagram here.

The Government Project

The goal

The project involved adding new features to System A , a governmental self-service system for citizens. A user of role Citizen would invoke Use Cases in System A via a web interface.

A different System B would then be notified, process the data and make a result available. This result would then have to be displayed for the Citizen.

Sounds pretty straight forward: Two systems collaborate to receive, process and make a result available. The Citizen interacts with System A through a web application interface, System A and B interact though web service API.

I assumed the role as architect for System A. It was my responsibility to carry the changes from idea to production. I had a peer architect who was responsible for the changes in System B. We were organizationally separated in two separate companies, both being suppliers to the government agency.

Designing the solution

Throughout the project the above goal was the working hypothesis from a helicopter perspective. In conjunction, the systems should receive the request from the Citizen, process it, and display the result.

When I run software projects, I take time to repeat the synopsis of the project out loud during select project meetings. The purpose of this is to continuously verify that the hypothesis still holds up, much like a business case.

I received positive confirmation every time we went through the synopsis. By intuition, however, I felt that there was something off in the understanding and timing of the communications between System A and System B. I was fearing uncovered assumptions. After multiple verifications from my peer architect governing System B, I asked him to do a short white board session with me and drew the expectations of the aforementioned Use Case in a Sequence diagram. It looked roughly like this:

The user Submits data to System A. This is forwarded from System A to System B. Hereafter System A requests the full response from System B. System A returns the result to the Citizen as a dialog.

Something I personally enjoy is when I communicate a key point and the receiver has a fresh idea or insight based on it. I simply love sharing ideas and inspiring, and I am fortunate to experience this when we run our Advanced Software Mastermind conferences ↗. It happened during this conversation as well. This time, however, there was also a little bit of fear to be found in my colleague’s expression.

This time, however, there was also a little bit of fear to be found in my colleague’s expression.

He responded that they were actually not implementing it like that. Close, but not quite. He assured me that with their design the result would be the same, and went into further detail. System B would receive the request and store the information. They would then process all requests during the night in a batch job. In essence, their Use case diagram looked like this:

This Use case diagram was never formalized and therefore never disclosed. It was only in the minds of the other architect and his developers.

But while the result of processing is the same, the end result is far from the same. This had rather large implications for the project. On our side, we expected immediate processing to be able to display the result right away. This was a reasonable requirement given that the processing was relatively simple and lightweight. There was no countering constraints, such as a need for background processing.

On the System B side, they followed an implementation pattern they had traditionally used. It was therefore an unspoken part of the implementation that would have implications for the Citizen’s experience with a government system. It would require the Citizen to come back at a later time. It might have required us to factor in a notification communication channel, which was not part of the current project scope.

Fortunately, this short conversation brought the assumption to light and they changed the solution model and implementation in System B.

Conclusion

While we can define behavior in the Use Case diagrams, they mostly only hint about the timing of the user interactions. Defining and discussing important interactions by using Sequence diagrams is at least equally valuable and important. In a worst case scenario, we could have reached the deadline of the project with both solution models in play. We could have still positively verified that we could receive the information, process it, and display the result, all without having a functioning system. It could have been really unfortunate and costly.

Maybe it is not a surprise, but the second takeaway is that this could have been avoided if we had started to diagram this interaction earlier. And so it goes – sometimes diagramming feels like overkill or feels premature, but only until you are on the other side and find that your solution has become more complex (model, project, team) and that you should have started earlier. It is a constant balancing act. Personally, I prefer to manage risk by starting early. I urge you to do so as well.

Some notes on Sequence diagrams:

  • Just as mentioned in the Class diagram article, Sequence diagrams also exist in different ways based on the context and phase. Early diagrams do not need much detail as long as they work as a conversation piece.
  • It can be argued that we could have emphasized the agile project approach even more to better uncover assumptions. But a pure agile methodology wasn’t an option in this collaboration, for many reasons outside the control of the technical organizations. We don’t get to chose everytime.

Resources: