Creating PlantUML images

Published

July 8, 2024

We use PlantUML to create diagrams across most of content, such as:

  1. C4 diagrams to visualise the software architecture.
  2. Sequence diagrams that visualise how and in what order things work together.

To create PNG images of the PlantUML files, open a Terminal while inside the project that has the PlantUML files and that has the justfile, and run the command:

just generate-puml-all

If you want to generate a specific image, run:

just generate-puml PATH/TO/PUML

You need to have both Docker and Just installed and have Docker running in the background in order for these commands to work. To see how to install these programs, check out the entry on software) for more details.

Style guide

When you create a PlantUML diagram, please follow the style guide below:

  1. Use the Seedcase theme, see below.
  2. Use sentence case (capitalise the first word only) for diagram titles and texts.
  3. Ensure that you use the same wording and ordering of elements in the diagram as in the surrounding text.
  4. For C4 diagrams, add a legend by writing SHOW_LEGEND() or SHOW_FLOATING_LEGEND() at the end of the diagram.

Seedcase theme

We have created a PlantUML theme that we use across all our PlantUML diagrams. This theme is located in the seedcase-theme repository and is synced to the remaining Seedcase repositories. In these repositories, the theme is located in the _extensions/seedcase-project/seedcase-theme directory.

To include the theme in a PlantUML file, add the following line at the top of the file:

@startuml diagram-name

!theme seedcase from https://raw.githubusercontent.com/seedcase-project/seedcase-theme/main

[add your diagram code here] 

@enduml