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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

sequenceDiagram
    participant User
    participant WebApp
    participant EmailService
    participant SMSService

    User->>WebApp: Register with email/phone number
    WebApp->>WebApp: Validate input
    alt Email Address
        WebApp->>EmailService: Send command (email)
        EmailService->>EmailService: Generate confirmation email
        EmailService->>User: Send email for confirmation
    else Phone Number
        WebApp->>SMSService: Send command (SMS)
        SMSService->>SMSService: Generate confirmation SMS
        SMSService->>User: Send SMS for confirmation
    end
    User->>WebApp: Confirm registration
    WebApp->>WebApp: Validate confirmation
    WebApp->>WebApp: Complete registration process
    WebApp->>User: Registration successful

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

sequenceDiagram
    participant web as Web Browser
    participant blog as Blog Service
    participant account as Account Service
    participant db as Storage
    participant mail as Mail Service

    Note over web,db: The user must be logged in to submit blog posts
    web->>+account: Logs in using credentials
    account->>db: Query stored accounts
    db->>account: Respond with query result

    alt Credentials not found
        account->>web: Invalid credentials
    else Credentials found
        account->>-web: Successfully logged in

        Note over web,db: When the user is authenticated, they can now submit new posts
        web->>+blog: Submit new post
        blog->>db: Store post data

        par Notifications
            blog--)db: Store in-site notifications
            blog--)mail: Send notification to subscribers
        and Response
            blog-->>-web: Successfully posted
        end
    end

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:

1. Participants:

   • 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.

2. Authentication Process:

   • 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.”

3. 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.”

4. Notes:

   • 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.

Wrapping up

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.