Gatsby Logo



PlantUML can be used to create several UML diagram types from a simple text file description. It can run from command line, editor (e.g. VSCode plugin), browser (e.g. Chrome browser) or online service via browser.

  • For standard UML diagrams (class diagrams, sequence diagrams) auto-generation is a good option.
  • For C4 architecture (Context, Container, Component, Class), it is ideal and C4 templates exist.
  • For complex non-UML diagrams, where the arrangement of parts is important to convey information, it may be better to just draw a simple Box-and-Line diagram.


  1. Bring architecture closer to the code so that it is in sync with the code:

    1. code is developed consistent with the architecture
    2. architecture diagrams and description is current and correct
  2. Remove the initial friction to create diagrams - by auto-generating them
  3. Diagram source text files are version-controlled in GIT in relevant source code repo
  4. Consistent diagrams - that can be easily interlinked

PlantUML Examples gives many examples of PlantUML diagrams.

keystore example of a sequence diagram I created

VSCode PlantUML Extension

VSCode Plantuml Extension makes it easy to create and edit plantuml diagrams. It includes a real-time preview.

Plantuml for C4 Architecture

C4 templates exist to create PlantUML diagrams according to the C4 template.

Use Local Copy of C4 Templates

For each of the template files C4Context.puml, C4Context.puml, C4_Component.puml comment out the includeurl, and uncomment the include, directive.

' !includeurl
' uncomment the following line and comment the first to use locally
!include C4_Container.puml


Add C4 Snippets to VSCode Editor

VSCode supports snippets that predict words as you type. VSCcode Snippets for C4 can be installed per See


Some standard libaries are available for PlantUML. See for what is supported in official release of PlantUML.

Plantuml for AWS

Plantuml for AWS uses the icon set from AWS and converts these to sprites for use with PlantUML.

git clone

Simple Example


More Complex Example

aws big

PlantUML Sprites

PlantUML supports sprites (small graphic elements). Given we want to make diagrams communicate quickly and clearly, using sprites (rather than just boxes) is very effective.

PlantUML Sprite Examples

Some good examples of where PlantUML Sprites are used:

PlantUML Create a Sprite

It's easy to create your own sprites from existing icons.

Start with a 100x100 person icon png


Convert to sprite of different resolutions as follows

Download plantuml.jar

 java -jar plantuml.jar -encodesprite 4 images/C4person100.png > C4person4.sprite
 java -jar plantuml.jar -encodesprite 16 images/C4person100.png > C4person16.sprite
 java -jar plantuml.jar -encodesprite 8 images/C4person100.png > C4person8.sprite


Create Diagram with our Sprites

See source code

sprite $C4person100Small [16x16/16] {

sprite $C4person100Big [100x100/16] {
# removed rest of sprite here for clarity

Bob : <$C4person100Small> Small
Alice : <$C4person100Big> Big

Alice -> Bob 


PlantUML HyperLinks

PlantUML supports hyperlinks in output SVG images. This allows diagrams to be linked together, and for a user to easily navigate by clicking around per Shneiderman's mantra:

Overview first, zoom and filter, then details-on-demand


actor Bob [[]]
actor "This is [[ Alice]] actor" as Alice
Bob -> Alice [[]] : hello
note left [[]]
  a note with a link
end note
Alice -> Bob : hello with [[{Tooltip for message} some link]]
note right [[]] : another note
note left of Bob
' You can use [[ links in notes]] also.
end note


  1. homepage
  2. is a PlantUML showcase
  3. free online site where you can copyNpaste the text description to auto-generate a diagram
  4. free online site where you can copyNpaste the text description to auto-generate a diagram
  5. NPM package using autodoc and C4 template
  6. Good article that makes reference to a good book "Agile Modelling - Scott Ambler"