Introduction

This blog post looks at sequence diagrams in general, how utilizing techniques like diagrams as code can bring them under source control, and what implications the diagrams have on the developer flow.

What are Sequence Diagrams?

UML Sequence Diagrams are a powerful tool in software engineering for visualizing the interactions between actors or objects in a system over time. They should be scoped to a particular business or technical process. Sequence diagrams illustrate, amongst others:

• The objects or actors involved in the interaction with their activation points
• The sequence of messages exchanged between these objects. Do not necessarily think about messages as in a service bus
• The order in which these messages occur
• Type of messages, synchronously, async
• Control structures like loops, conditionals, and parallels

I am sure there are UML Sequence diagram rules that I violate. However, the important part is that the diagrams are clear and convey the meaning to the reader.

Creating Sequence Diagrams

While traditionally drawn using WYSIWYG tools, modern approaches include diagram as code methodologies. Tools like Mermaid allow you to create sequence diagrams using simple text-based syntax, which can be version-controlled and more easily maintained.

With diagrams as code, you can quickly iterate over a particular flow, make changes, and discuss things with your partners. All without fighting with the tool and keeping the complete history of any changes. I wrote another blog post on why I chose Mermaid and diagram as code in general.

Here's an example of a sequence diagram involving an actor and multiple objects:

This diagram illustrates a typical e-commerce flow involving a customer interacting with a web application, which communicates with various backend systems like an order system, inventory system, and payment gateway. It showcases how multiple systems interact to complete a single user action, demonstrating the complexity and interconnectedness of modern software architectures.

Sequence diagrams have features for alternative flows, optional paths, parallel paths, and loops. In my experience, it is easier to split out multiple diagrams if the different flow paths become too big. The example above shows the alt flow feature.

I use the iamcco/markdown-preview.nvim: markdown preview plugin for (neo)vim (github.com) plugin. It allows for a quick and iterative sequence diagram creation flow. There are plugins for other editors, or you can use the online tool at https://www.mermaidchart.com/play.

Benefits of Using Sequence Diagrams

• Clarity: They provide a clear visual representation of complex interactions
• Communication: They facilitate better understanding among team members and stakeholders
• Design: They help in identifying potential issues in system design early in the development process
• Documentation: They serve as valuable documentation for system behavior

With Pull/Merge requests, we get valuable feedback on the diagrams as code part of the regular developer flow. Often, I find myself creating many versions and changes to the flow during pair programming or the QA phase.

Design QA

In my last projects, I introduced the notion of Design QA, which is a step before the implementation phase. In this step, the developers generate different ideas, explore the problem space, and propose ways to solve the problem before starting on the detailed implementation. Sequence diagrams are a great way to document the proposed solutions and kick off this phase discussion. Ideally, this design phase should be an integrated part of the implementation phase. However, I find that by introducing design qa , we get more focus on design. Once it is a natural part of the implementation phase, such as coding, you might consider removing the phase.

Conclusion

UML Sequence Diagrams are invaluable assets in the software development lifecycle. They provide a clear visual representation of complex system interactions, enhancing communication among team members and stakeholders. By incorporating sequence diagrams into the design process, mainly through diagram-as-code, developers can iterate quickly, version control their designs, and seamlessly integrate this documentation into their workflow.

The introduction of Design QA, where sequence diagrams play a crucial role, further emphasizes their importance in exploring and documenting potential solutions before implementation. This approach improves the overall design process and helps identify and address potential issues early in the development cycle.

Sequence diagrams can serve not just as documentation but as a collaborative tool that bridges the gap between conceptual understanding and practical implementation. By making sequence diagrams a natural part of the development process, teams can improve efficiency, reduce misunderstandings, and create more robust and maintainable software systems.