Software design diagrams using PlantUML

Recreating the Mermaid diagrams described in Creating software with modern diagramming by Ashley Peacock using PlantUML

Contents

  1. Domain model (class diagrams)
  2. User flows (sequence diagrams)
  3. See also

See Installing PlantUML for setup and basic usage instructions.

These diagrams are generated using the -Smonochrome=true and -Sshadowing=false flags.

Domain model (class diagrams)

Based on: Ch 1. Document your domain and Ch 2. Enhance your domain model.

Entities in a domain model and how they are related (class diagram)

Association: loose relation, exist independently, neither owns the other. example: title – genre

Composition: the “child” entity cannot exist independently of the “parent”. examples: title – season, season – episode, title – review

Aggregate: can exist independently, but one is the “parent” (owner of the relationship). example: title – actor

@startuml
Title -- Genre

Title *-- Season
Title *-- Review
Season *-- Episode

Title o-- Actor
@enduml

Domain model showing entity relationships

Generalisation: represents inheritance (subtypes). example: title ∈ {tv show, film, short}

@startuml
"TV show" --|> Title
Short --|> Title
Film --|> Title
@enduml

Domain model showing inheritance

Descriptions of the relationships can be added as labels on the vertices:

@startuml
Title -- Genre: "is associated with"

Title *-- Season: has
Title *-- Review: has
Season *-- Episode: contains
Season *-- Review: has
Episode *-- Review: has

Title o-- Actor: features

"TV show" --|> Title: implements
Short --|> Title: implements
Film --|> Title: implements

Viewer --> Title: watches
@enduml

Domain model with description labels

Multiplicity of a relation (one-to-one, one-to-many, many-to-many, etc.) is described by specifying the cardinality on each end of the vertex. For example, each title (1) has zero or more seasons (0..*).

@startuml
Title "1..*" -- "1..*" Genre: "is associated with"

Title "1" *-- "0..*" Season: has
Title "1" *-- "0..*" Review: has
Season "1" *-- "1..*" Episode: contains
Season "1" *-- "0..*" Review: has
Episode "1" *-- "0..*" Review: has

Title "0..*" o-- "1..*" Actor: features

"TV show" --|> Title: implements
Short --|> Title: implements
Film --|> Title: implements

Viewer "0..*" --> "0..*" Title: watches
@enduml

Domain model with cardinality labels

Improving the visual style:

title Streamy Domain Model

' added to improve readability
class "\n\nTitle\n\n" as Title

/' alternative
class Title {
  \n
  --
  \n
}
'/

Completed domain model

Note: Unlike in Mermaid, it isn’t possible to add a hyperlink to an entity in a class diagram, though it is possible on a Gantt diagram.

User flows (sequence diagrams)

Based on: Ch 3. Visualise application and user flows.

To model the interactions between different systems, use a sequence diagram with data flow represented as messages sent between nodes (lifelines).

Using actor, database, etc. instead of participant changes the shape with which the node is represented.

The participants don’t have to be declared upfront, but this allows fixing the order in which they appear on the diagram.

@startuml
title User sign-up flow

actor Browser
participant "Sign-up service" as Signup
participant "User service" as User

Browser -> Signup : GET /sign_up
Signup --> Browser : 200 OK (HTML page)
@enduml

User flow showing request and response

Alternative paths: Use an alt/else/end group to show branching logic (e.g. happy and unhappy path).

Browser -> Signup : POST /sign_up
Signup -> Signup : Validate input

alt invalid input
  Signup --> Browser : Error
else valid input
  Signup -> User : POST /users
  User --> Signup : 201 Created (User)
  Signup --> Browser : 301 Redirect (Login page)
end

User flow showing alternative paths

Asynchronous messages:

Signup -> User : POST /users
User -->> Kafka : User Created\nevent published
User --> Signup : 201 Created (User)

User flow showing an asynchronous message

Lifeline activation can indicate how complex an interaction is by how many messages are passed before a node returns its response.

Manually activate and deactivate a node:

Browser -> Signup : GET /sign_up
activate Signup
Signup --> Browser : 200 OK (HTML page)
deactivate Signup

Shortcut using ++ and --:

Signup -> User ++ : POST /users
User -->> Kafka : User Created\nevent published
User --> Signup -- : 201 Created (User)

Or use return to deactivate the last node that is still activated:

Browser -> Signup ++ : POST /sign_up
/' ... '/
return 301 Redirect (Login page)

User flow showing alternative paths

A note can be used to highlight or provide additional context.

User -->> Kafka : User Created\nevent published
note right : note on the right
note left of Kafka : note below & to the left
note left of Kafka
  note that spans
  multiple lines
end note
note over User, Kafka : note that spans over specific nodes

User flow with notes around a message

The full diagram specification (with autonumbering for the first few messages):

@startuml
title User sign-up flow

actor Browser
participant "Sign-up service" as Signup
participant "User service" as User
participant Kafka

autonumber

Browser -> Signup : GET /sign_up
activate Signup
Signup --> Browser : 200 OK (HTML page)
deactivate Signup

Browser -> Signup ++ : POST /sign_up
Signup -> Signup : Validate input

autonumber stop

alt invalid input
  Signup --> Browser : Error
else valid input
  Signup -> User ++ : POST /users

  User -->> Kafka : User Created\nevent published
  note left of Kafka
    other services take action
    based on this event
  end note

  User --> Signup -- : 201 Created (User)
  return 301 Redirect (Login page)
end
@enduml

Completed user sign-up flow

Note: Unlike in Mermaid, it isn’t possible to add a menu with hyperlinks to a participant.

See also