7. Tricked Out Diagrams (aka Diagram Annotation)

!define osaPuml https://raw.githubusercontent.com/Crashedmind/PlantUML-opensecurityarchitecture2-icons/master
!include osaPuml/Common.puml
!include osaPuml/User/all.puml
!include osaPuml/Hardware/all.puml
!include osaPuml/Misc/all.puml
!include osaPuml/Server/all.puml
!include osaPuml/Site/all.puml

. Mary is a Developer in the Product team. She has a Windows 10 PC and an Android phone.
. Bob is a Manager in the Accounts team. He has Mac and an iPhone.
. Ivan is an IT guy who looks after the server. 
. They connect to the network hub, and via a firewall to the Internet.

Title <$osa_site_branch*.5> \nNetwork Diagram  

skinparam handwritten true
<font color=red> Warning:</font>
This is a draft! <&box><color:Red><$osa_warning*.5></color>


' Users
together {
osa_user_green_developer(Mary, "Mary", "Product team", "Developer")
osa_user_green_operations(Ivan, "Ivan", "IT Team", "Server Admin")
osa_user_green_business_manager(Bob, "Bob", "Accounts team", "Manager")
note left
  * Look at Bob
  * Here he is
  ** Yes he really is
end note

' Devices
together {
osa_desktop(pc, "", "Windows 10", "PC")
osa_laptop(mac, "", "Mac", "Mac")
osa_iPhone(iphone, "Dynamic IP", "iPhone 11", "Phone")
osa_iPhone(android, "Dynamic IP", "Android 10", "Phone")
osa_server(server, "", "Ubuntu Server 20.04 LTS", "Server")

' Network

osa_device_wireless_router(wifiAP, "", "Network")
osa_hub(hub, "Office hub", "Hub")
osa_firewall(firewall, "", "Network")
osa_cloud(cloud, "Internet", "Network")

Mary --> pc: source code
Mary --> android: social media

Bob --> mac: financial info
Bob --> iphone: phone calls

Ivan --> server: configuration

iphone --> wifiAP: <$osa_wireless_network>
android --> wifiAP: <$osa_wireless_network>
wifiAP --> hub

server --> hub
mac --> hub
pc --> hub

hub --> firewall: <$osa_lightning>

firewall --> cloud: <$osa_warning*2>

    |= Color |= Type |= Description |
    | <size:11><back:#Red>Mary           </back></size>|    <color:Red><$osa_user_green_developer*.4></color> | Mary details... This is a stdlib sprite |
    | <size:11><back:#DarkGreen>Ivan           </back></size>|    <color:DarkGreen><$osa_user_green_operations*.4></color> | Ivan details... |
    | <size:11><back:#Orange>Bob           </back></size>|    <color:Orange><$osa_user_green_business_manager*.4></color> | Bob details... |
    | <size:11><back:#Purple>Box           </back></size>|    <color:Purple><&box></color> | A Box. This is an openiconic sprite |

caption Acme Corp. Network Diagram as at %date("yyyy.MM.dd' at 'HH:mm")

center footer %filename() rendered with PlantUML version %version()\nThe Hitchhiker’s Guide to PlantUML enduml <&box> <$osa_user_large_group*.5>

Diagram with Annotation features

playbuttonAnnot Press to play around with this diagram source online.

Various annotations can be added to the diagrams e.g. title, caption, header, footer… These annotations can include:

  • Formatted text

  • Creole Sprites or Stdlib Sprites can be added to these annotations per example diagram here.

  • PlantUMLPreProcessor like filename, date…


You can also add creole sprites or stdlib sprites to arrows.

Some examples are shown in the diagram here.


The example diagram here shows all of these annotations in one diagram.

In general, “less is more”, so use these annotations if/where they add value and clarity to the audience.

7.1. Notes

Notes can be added to diagrams. These can include https://plantuml.com/creole syntax e.g. for bullets, text formatting.

Creole Sprites can be added to Notes. But this causes bullets to stop working. So, it’s creole sprites or bullets but not both.

Stdlib Sprites can not be added to notes.

7.2. Handwritten

See https://plantuml.com/handwritten.

Handwritten gives a wavy effect to diagrams. This can be useful to differentiate between e.g. a raw proposal versus an approved proposal. It can be set to true or false ala skinparam handwritten true.

7.3. Title

Various formatting options are available per https://plantuml.com/commons.


See https://plantuml.com/commons.

7.6. Caption

See https://plantuml.com/commons.