Application Flow Diagrams

I find it useful at the start of projects to diagram the high-level interactions I am aiming for between systems, before getting into the nitty-gritty.

Furthermore, these high-level interactions can be discussed with non-technical colleagues to ensure what you're planning on building actually fulfils the criteria of the project. That's another benefit to application flow diagrams: we can use them to explain the flow we're expecting to build to other engineers, or even non-technical colleagues such as product managers.

We can use a sequence diagram for this use case. A common use case I've found sequence diagrams to excel at is when getting approval to build a brand new system. In most companies, this will need to be approved by an architect or group of architects, and involves some form of documentation, and likely a presentation. I've attended the approval meeting many times, and you can see the struggle people have understanding the interactions between this new system and the existing systems when there's just a wall of text.

When I had to present a proposal for a new system at this meeting, my document was supplemented by sequence diagrams. Others in the company would complain that they struggled to get their ideas across, or it was hard to get an approval, but my experience was quite different. I didn't even use much of the text in the document, I simply presented the sequence diagrams, and everyone found it very easy to understand what I was proposing. Ultimately, I received approvals relatively quickly.

This isn't just the case for sequence diagrams too, almost any time you're presenting something, consider whether a diagram would be a better way to explain it, rather than words on a slide, or just talking at people without any visual aids.

We will lean on Unified Modelling Language (UML) to model our application flows, this time leveraging sequence diagrams. The Unified Modelling Language is a series of diagrams designed to provide a number of ways to document the design of a system.

There will be many flows in a real-world application, typically I tend to only diagram the happy path, and any particularly gnarly unhappy paths.

What Does A Sequence Diagram Look Like?

Of all the diagrams, I would argue sequence diagrams are the easiest to create and understand. Let's take a look at one:

          sequenceDiagram
            title User Sign Up Flow
            
            actor Browser
            participant Sign Up Service
            participant User Service
            participant Kafka
            
            Browser->>Sign Up Service: GET /sign_up
            activate Sign Up Service
            Sign Up Service-->>Browser: 200 OK (HTML page)
            deactivate Sign Up Service
            
            Browser->>+Sign Up Service: POST /sign_up
            Sign Up Service->>Sign Up Service: Validate input
            
            Sign Up Service->>+User Service: POST /users
            User Service--)Kafka: User Created Event Published
            Note left of Kafka: other services take action based on this event
            User Service-->>-Sign Up Service: 201 Created (User)
            Sign Up Service-->>-Browser: 301 Redirect (Login page)
        

This diagram was created using diagrams as code.

Due to their simplicity, we can easily see the application flow for a user sign up, using this sequence diagram. In essence, it shows the required flow to complete a business transaction. It's very high-level, there are no specifics here, but that's the point: we want to give a high-level overview of how a series of interactions between applications work.

Learn To Create Sequence Diagrams

That rounds out this introduction to application flows with sequence diagrams.

The diagram above was created using a tool called MermaidJS. It allows you to easily create a variety of diagrams in Markdown-like markup, and quickly convert into a rendered diagram wherever you need it.

Want to learn more? I cover how to create application flow diagrams, along with a number of other use cases and diagrams, in my book: Creating Software Using Modern Diagramming Techniques, published via The Pragmatic Programmers.