Using ChatGPT to generate sequence diagrams
Diagrams 🙄 are important pieces of documentation, but (some) are incredibly boring to put together. This is especially true as nowadays diagrams-as-code is the best practice - and I don’t disagree but it does mean having to go through the learn ➡ remember ➡ re-learn (repeat 🔁) loop of your syntax of choice.
Take the sequence diagram, a classic that for some software projects is still a must have on the path to Production - particularly if you work with the NHS and need to complete a SCAL. This week I started to put together a draft sequence diagram for a software project my team is close to wrapping up - I started off in Miro but quickly found myself searching the web for how do I make a line straight in Miro (turns out you hold shift while drawing a line) and quickly realised that perhaps Miro wasn’t the best choice. I was about to reach for pen and paper then remembered an article I read recently about using generative AI to build Mermaid diagrams (warning link will take you to a Medium article).
Generating sequence diagram
So instead of reaching for pen and paper, I headed over to ChatGPT. I won’t share the exact details of the system I wanted to generate a sequence diagram for (since that’s work product) but here’s an example.
The response from ChatGPT included the following Mermaid syntax
which generates the following diagram
ChatGPT has made a few assumptions, which it has included in the sequence diagram - this isn’t all too surprising given that website registration is a very common pattern.
Asking ChatGPT to explain a sequence diagram
The neat thing about diagrams as code, especially when using the Mermaid syntax since it’s so well known, is that you can use ChatGPT to explain what’s going on. Take the following example
This diagram is generated from the following Mermaid syntax
To which ChatGPT responds with the following
This sequence diagram represents the interaction flow between different participants in a system when a user attempts to submit a new blog post. Here’s the explanation of what’s happening in the diagram:
- Web Browser (web): Represents the user’s web browser.
- Blog Service (blog): Manages the blog-related functionalities.
- Account Service (account): Handles user authentication and account-related operations.
- Storage (db): Represents the database where account information and blog posts are stored.
- Mail Service (mail): Manages sending notifications to subscribers via email.
- The user attempts to submit a new blog post, but first, they must be logged in.
- The web browser sends a login request to the Account Service (account) with user credentials.
- The Account Service queries the stored accounts in the database (db).
- If the credentials are not found, the Account Service responds back to the web browser with “Invalid credentials.”
- If the credentials are found and valid, the Account Service responds with “Successfully logged in.”
Post Submission Process:
- After successful authentication, the user is allowed to submit a new blog post.
- The web browser sends a request to the Blog Service (blog) to submit the new post.
- The Blog Service stores the post data in the database (db).
- Simultaneously, two parallel activities occur:
- Notifications: The Blog Service stores in-site notifications related to the new post in the database (db) and also sends a notification to subscribers via the Mail Service (mail).
- Response: The Blog Service responds back to the web browser with “Successfully posted.”
- There is a note indicating that the user must be logged in to submit blog posts, emphasizing the requirement for authentication.
- Another note states that after authentication, the user can submit new posts, indicating the transition from the authentication phase to the post submission phase.
In summary, the diagram captures the sequence of interactions between the user’s web browser, the Account Service, the Blog Service, the database for data storage, and the Mail Service for notifications. The diagram illustrates the authentication process, the submission of a new blog post, and the parallel activities related to notifications and response handling.
This week when I set out to put together a draft sequence diagram, I didn’t expect to complete it - hence the “draft” - because I thought it was going to be painful to put together something I would be happy to share externally. But using ChatGPT I was able to get the task done in the space of about 30 minutes, and that includes the time I spent fiddling with Miro and learning how to make lines straight (yep, hold shift while drawing the line).
ChatGPT performs really well with a problem like this, there is scope for ambiguity but I found that for the system I described, ChatGPT did a good job of drawing the first diagram. The problem was when I asked it to expand the diagram to add a bit more detail, it failed pretty miserably but that could have been down to my prompt not being very clear. Instead of getting into the loop of refining my prompts I made the changes I wanted myself, building on what ChatGPT had already generated.
After using ChatGPT to draw up a sequence diagram I tried a few other types of diagrams, specifically I was interested in whether ChatGPT could draw up some architecture diagrams - I tried a few prompts with Mermaid syntax and PlantUML but didn’t get terribly far and ChatGPT didn’t do a great job so will need to give it another try next time.