Skip to main content

A Recommendation for PlantUML

PlantUML is a language for creating UML diagrams from text. If you ever need to draw diagrams, PlantUML is the go-to tool.

In some environments such as VS Code, it can be rendered directly within Markdown. Note that some syntax is occasionally unsupported and may cause preview errors.

  • < often fails to render correctly

Using VS Code as your development environment makes things very productive (see below).

What Can PlantUML Do?​

You can write diagram figures as text:

  • Class diagrams
  • Package diagrams
  • Object diagrams
  • Activity diagrams
  • Use case diagrams
  • State chart diagrams
  • Sequence diagrams
  • Collaboration diagrams
  • ER diagrams
  • etc...

It is most commonly used for sequence diagrams and ER diagrams.

Pros and Cons​

  • Since diagrams are managed as text, they can be version-controlled with Git
  • No need to worry about fine-tuning layout
    • Just define the figures and relationships, and lines are drawn automatically, freeing you from the hassle of misaligned elements
    • On the flip side, you cannot fine-tune the layout even if you want to, but you can accept that as a limitation
  • You need to learn the syntax
    • There is no GUI tool
    • In practice, copying and combining examples from the official documentation is sufficient

Examples​

Examples of commonly used diagrams.

ER Diagram​

The basic layout you should know is this:

point.png

The way logical and physical names are written may vary by individual, but the strength of PlantUML is that even when the database is complex, you don't have to worry about how to draw lines or where to position tables.

Sequence Diagram​

Example​

  • Extracting the necessary parts from this diagram will probably make things easier to understand
  • Most major sequence diagram components are used here
  • Due to a rendering bug in mkdocs, the code is also included below.
@startuml

participant "APIサーバー" as A

box "Apache Kafka" #LightBlue
participant "推論Topic" as B
participant "停止Topic" as C
end Box

participant "推論サーバー" as D

[-> A: API受信

A ->> B: 推論のキューイング
activate B

hnote over B #LightPink: Waiting...
note right: 推論サーバーが空き次第処理

B ->> D: 推論の実行
activate D #IndianRed
note right
自動終了の条件
- 回数
- 時間制限
- 処理の完了
end note

D ->> B: キューの受取通知
deactivate B

D -->> A: 処理段階で随時ステータス送信

alt 手動で終了させる場合

    A ->> C: 停止信号をキューイング
    activate C

    hnote over C #LightPink: Waiting...


    C ->> D: 別プロセスで受信
    note right
    複数台の推論サーバーがある場合、
    すべてのサーバーが受信する
    end note

    D ->> D: 推論処理の停止
    note right
    該当のIDが処理中の場合に停止させる
    > 推論中の別プロセスへ通信
    該当していない場合は何もしない
    end note

    D ->> C: キューの受取通知
    deactivate C

end

D ->> A: 終了通知
deactivate D

@enduml

Placing Files in a Git Repository​

The standard approach is to place a file named plantuml.pu at the root of the repository. There are also several other file extensions to choose from based on your preference.

Writing in VS Code​

Basically follow the plugin's README.

Installation​

  1. Install the required tools
brew cask install java
brew install graphviz
  1. Install the VS Code plugin

Usage​

  1. Open a PlantUML file, press cmd+shift+p to open the command palette, and select Preview Current Diagram
  2. A split pane will appear on the right showing a real-time preview

If a PATH Error Appears When Previewing​

In the settings, find the PlantUML: Java configuration item and register the full path to your installed Java.

Reference: VS Code PlantUML view not showing due to Java path error