Technical

Shiny things sell, so embellish your PlantUML diagrams.

Juan Tenorio

02 May 2024 • 5 min read

Photo by James Harrison / Unsplash

On a previous post I showed you how to get your own UML editor.

https://darthseldon.net/plantuml-and-nginx-your-own-uml-designer/

Now here is a guide on how to make your diagrams more stylish.

Let's take a look at this simple sequence diagram.

@startuml
Client -> IDP: Authentication Request
IDP --> Client: Authentication Response
Client -> API: Get Products
API -> Database : Query Products
Database --> API : Products
API --> Client
@enduml

First, I would make it more verbose as it will describe better what the diagram is trying to explain.

@startuml

'header
title Stylish Sequence Diagram

'actors and participants
actor "Client" as client
participant "Identity Server Provider" as idp
participant "API" as api
participant "Products Database" as database

'interactions
client -> idp: Authentication Request
idp --> client: Authentication Response
client -> api: Get Products
api -> database : Query Products
database --> api : Products
api --> client

'footer
footer v1.0

@enduml

Note that instead of using literals we will be using declarations and aliases for the actors and participants.

Adding title and footer will show also what this diagram is about instead of guessing.

One of the advantages you can take is to import other puml definitions, but the included standard library will be your best weapon.

Since I work with Azure quite often, I always refer to the Azure-PlantUML library.

You can see all the definitions; if you need to use a specific sprite, you can import it and use it like this.

@startuml

'standard libraries
!include <C4/C4_Container>
!include <azure/AzureCommon>
!include <azure/Databases/AzureSqlServer>

'header
title Stylish Sequence Diagram

'actors and participants
actor "Client" as client
participant "Identity Server Provider" as idp
participant "API" as api
participant "<$AzureSqlServer>\nProducts Database" as database

'interactions
client -> idp: Authentication Request
idp --> client: Authentication Response
client -> api: Get Products
api -> database : Query Products
database --> api : Products
api --> client

'footer
footer v1.0

@enduml

We are including the C4 icons (will discuss the C4 model in another post), azure common library with the Azure SQL Server sprite.

And to insert the sprite use the sprite name as a variable.

<$AzureSqlServer>

Now let's take a look with all the icons

@startuml

'standard libraries
!include <C4/C4_Container>
!include <azure/AzureCommon>
!include <azure/Databases/AzureSqlServer>
!include <tupadr3/common>
!include <office/Servers/application_server>
!include <office/Concepts/application_generic>

'header
title Stylish Sequence Diagram

'actors and participants
actor "Client" as client
participant "<$application_server>\nIdentity Server Provider" as idp
participant "<$application_generic>\nAPI" as api
participant "<$AzureSqlServer>\nProducts Database" as database

'interactions
client -> idp: Authentication Request
idp --> client: Authentication Response
client -> api: Get Products
api -> database : Query Products
database --> api : Products
api --> client

'footer
footer v1.0

@enduml

Note that I added one more library and 2 more sprites, here is the reference to the library.

Now will place activation and interaction numbers.

@startuml

'standard libraries
!include <C4/C4_Container>
!include <azure/AzureCommon>
!include <azure/Databases/AzureSqlServer>
!include <tupadr3/common>
!include <office/Servers/application_server>
!include <office/Concepts/application_generic>

'header
title Stylish Sequence Diagram

'actors and participants
actor "Client" as client
participant "<$application_server>\nIdentity Server Provider" as idp
participant "<$application_generic>\nAPI" as api
participant "<$AzureSqlServer>\nProducts Database" as database

'interactions
autonumber "<b>[000]"
client -> idp: Authentication Request
activate idp
idp --> client: Authentication Response
deactivate idp
client -> api: Get Products
activate api
api -> database : Query Products
activate database
database --> api : Products
deactivate database
api --> client : JSON Products
deactivate api

'footer
footer v1.0

@enduml

Finally, I like to group the interaction logically and give it a little bit of formatting (spaces vs tabs, who remembers the show Silicon Valley? Very funny)

@startuml

'standard libraries
!include <C4/C4_Container>
!include <azure/AzureCommon>
!include <azure/Databases/AzureSqlServer>
!include <tupadr3/common>
!include <office/Servers/application_server>
!include <office/Concepts/application_generic>

'header
title Stylish Sequence Diagram

'actors and participants
actor "Client" as client
participant "<$application_server>\nIdentity Server Provider" as idp
participant "<$application_generic>\nAPI" as api
participant "<$AzureSqlServer>\nProducts Database" as database

'interactions
autonumber "<b>[000]"

  group Authentication
    client -> idp: Authentication Request
    activate idp
      idp --> client: Authentication Response
    deactivate idp
  end

  group Obtain Products
    client -> api: Get Products
    activate api
      api -> database : Query Products
      activate database
        database --> api : Products
      deactivate database
      api --> client : JSON Products
    deactivate api
  end

'footer
footer v1.0

@enduml

There are many other standard libraries and sprites to test, I will encourage you to try them and find your go to sprites.

Next post will be the C4 model with PlantUML.

Happy coding!!!