Diagramming

See Rendered PDF

Configure

• System: install plantuml (e.g. brew install plantuml)
• Emacs: install plantuml-mode. Configuration:

(setq plantuml-jar-path "/usr/local/Cellar/plantuml/1.2019.6/libexec/plantuml.jar")
(setq plantuml-jar-args '("-charset" "UTF-8" "-config" "~/plantuml.txt"))
(setq org-startup-with-inline-images t)
(add-to-list 'org-src-lang-modes '("plantuml" . plantuml))
(org-babel-do-load-languages
 'org-babel-load-languages
 '((plantuml . t)))

• C-c C-c in a source block to render a diagram.
• May need to org-toggle-inline-images to view inline.

Embedding a Diagram

#+begin_src plantuml :file output.png

Begin diagram

#+end_src

End diagram

#+STARTUP: inlineimages

Display diagrams inline (put at top of file)

Example

Bob -> Alice : Hello, alice

Use Case Diagrams

User -> (Start)
User --> (Use the application) : A small label

:Main Admin: ---> (Use the application) : This is\nyet another\nlabel

Sequence Diagrams

Arrows

-> or <-

Solid arrow

--> or <--

Dotted arrow

-\ or -/

Half arrowhead

-~\~, ->>, <<-, -//

Skinny arrowhead

->o

Arrow points to circle

<->

Bidirectional arrow

-[#red]->

Arrow color

[->, ->], [<-, <-]

Un-anchored lines

Example Sequence Diagram Arrows

Bob ->x Alice
Bob -> Alice
Bob ->> Alice
Bob -\ Alice
Bob \\- Alice
Bob //-- Alice
Bob ->o Alice
Bob o\\-- Alice
Bob <-[#green]-> Alice
Bob <->o Alice
Bob -> Bob
Alice -> Alice
[--> Bob
Alice -->]
[<-- Bob
Alice <--]

Participants

actor ActorName

Define an actor

boundary BoundaryName

Define boundary system

control ControlName

Define a control system

entity EntityName

Define an entity

database DatabaseName

Define a database

collections CollectionsName

Define a collection

Example Sequence Diagram

actor        Actor #red
boundary     Boundary #orange
control      Control #yellow
entity       Entity #green
database     Database #blue
collections  Collections #white
participant  Participant #white

Actor -> Boundary : To boundary
Actor -> Control : To control
Actor -> Entity : To entity
Actor -> Database : To database
Actor -> Collections : To collections
Actor -> Participant : To Participant

Sequence Numbering

autonumber <start>

Begin numbering at <start> or 1

Example autonumbering

actor        Actor #red
boundary     Boundary #orange
control      Control #yellow
entity       Entity #green
database     Database #blue
collections  Collections #white
participant  Participant #white

autonumber
Actor -> Boundary : To boundary
Actor -> Control : To control
Actor -> Entity : To entity
Actor -> Database : To database
Actor -> Collections : To collections
Actor -> Participant : To Participant

Page Titles, Headers, Footers

header <content>

Defines header content

title <content>

Defines title content

footer <content>

Defines footer content

Example Titles, Headers, Footers

title Sequence Title Example
header Sequence Diagrams
footer Page %page% of %lastpage%

actor        Actor #red
boundary     Boundary #orange
control      Control #yellow
entity       Entity #green
database     Database #blue
collections  Collections #white
participant  Participant #white

autonumber
Actor -> Boundary : To boundary
Actor -> Control : To control
Actor -> Entity : To entity
Actor -> Database : To database
Actor -> Collections : To collections
Actor -> Participant : To Participant

Sequence Grouping Boxes

alt <title> ... else <title> ... end

Define alternates

loop <title>

Steps in group are looped

par

Steps run in parallel

break

Steps supercede subsequent steps

critical

Steps must not be interleaved

group <title>

Custom grouping

Example Sequence Diagram - Alternates

title Sequence Diagram with Alternate Paths

Alice -> Bob: Authentication Request

alt Successful authentication

        Bob -> Alice: Authentication Accepted

else Authentication failure

        Bob -> Alice: Authentication Failure

else Connection failure

        Alice -> Bob: Repeat request
end

Example Sequence Diagram - Loops

title Sequence Diagram with Loop

Alice -> Log : Log attack start
loop 1000 times
        Alice -> Bob: DNS Attack
end

Example Sequence Diagram - Parallel

title Sequence Diagram with Parallel

Alice -> Log : Log attack start
par
        Alice -> Bob: DNS Attack
        Alice -> Bob: Fuzz Attack
        Alice -> Bob: Social Engineering Attack
end

Notes

Notes relative to message

Put note below the message

note left: <note text>

Add a note to the left

note right: <note right>

Add a note to the right

note left ... end note

Multiline note

Notes relative to participant

Put note below the participant

note left of <Participant>

Place note left of participant

note over <Participant>

Place note over participant

note right of <Particpant>

Place note right of participant

Example Sequence Diagram With Notes

title Sequence Diagram With Notes

participant Alice
participant Bob

Alice -> Bob : Good Morning. How was your weekend?
note left: Alice greets Bob.

Alice <- Bob : Hi Alice! Great snow in Tahoe this weekend.
note right #E3DCCA: Bob greets Alice.

note left of Alice #E3DCCA
        This is displayed
        Left of alice.
end note

note right of Alice: This is displayed to the right of Alice.
note over Alice: This is displayed over Alice.
note over Alice, Bob #F9DEDE
        This is displayed
        over Alice and Bob.
end note

Formatting

**bold**

Bold text

//italics//

Italics text

""monospaced""

Monospaced text

--strikethrough--

Strikethrough text

__underline__

Underlined text

~~wavy underline~~

Wavy underline text

Example Sequence Diagram With Formatting

title Sequence Diagram With Formatting

participant Alice
participant "The **Famous** Bob" as Bob

Alice -> Bob : hello --there--
... Some ~~long delay~~ ...
Bob -> Alice : ok
note left
  This is **bold**
  This is //italics//
  This is ""monospaced""
  This is --stroked--
  This is __underlined__
  This is ~~waved~~
end note

Alice -> Bob : A //well formatted// message
note right of Alice 
 This is <back:cadetblue><size:18>displayed</size></back> 
 __left of__ Alice. 
end note
note left of Bob 
 <u:red>This</u> is <color #118888>displayed</color> 
 **<color purple>left of</color> <s:red>Alice</strike> Bob**. 
end note

Splits

== label ==

Insert a split

Example Sequence Diagram With Split

title Sequence Diagram With Splits

== Initialization ==

Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

== ==

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response

Delays & Spacing

...

A delay in the sequence

|||

Add extra Vertical Spacing

Example Sequence Diagram With Delays And Spacing

title Sequence Diagram With Delays and Spacing

Alice -> Bob: message 1
...
Bob --> Alice: ok
|||
Alice -> Bob: message 2
...5 minutes later...
Bob --> Alice: ok
||45||
Alice -> Bob: message 3
Bob --> Alice: ok

Lifelines

activate <id> or ++

Mark start of lifeline <id>

deactivate <id> or --

Mark end of lifeline <id>

autoactivate on

Turn on autoactivation

create <type> <name> or **

Create a participant

destroy <id> or !!

Destroy participant

return <label>

Deactivate lifeline with <label>

Example Sequence Diagram With Lifelines

title Sequence Diagram With Lifelines

participant User

User -> A: DoWork
activate A #4682AF
      
A -> A: Internal call
activate A #F9DEDE

A -> B: << createRequest >>
activate B

B -> C: DoWork
activate C

C --> B: WorkDone
destroy C

B --> A: RequestCreated
deactivate B
deactivate A

A -> User: Done
deactivate A

Example Sequence Diagram With Auto-lifelines

title Sequence Diagram With Auto-Lifelines
autoactivate on

participant User

User -> A: UserRequest
A -> A: Internal call
A -> B: << createRequest >>
B -> C: DoWork
return Work Done
return RequestCreated
return InternalResponse
return UserResponse

Example Sequence with Shortcut Lifelines

title Sequence Diagram With Shortcut Lifelines
alice -> bob ++ : hello
bob -> bob ++ : self call
bob -> bib ++  #005500 : hello
bob -> george ** : create
return done
return rc
bob -> george !! : delete
return success

Participant Creation

~create <participant type> <participant name>

Create a participant

Example Sequence Diagram With Participant Creation

title Sequence Diagram With Participant Creation
Bob -> Alice : hello

create Other
Alice -> Other : new

create control String
Alice -> String
note right : You can also put notes!

Alice --> Bob : ok

System Boundaries

box <name> <color> ... end box

Wrap in a box

Example Sequence Diagram With System Boundary

title Sequence Diagram With System Boundary

box "Internal Service"
        participant Bob
        participant Alice
end box
participant Other

Bob -> Alice : hello
Alice -> Other : hello

Entity Diagrams

Entities

entity EntityName

Define an entity

* indentifying_attribute

Identifying attribute

--

Divider

* indentifying_attribute

Identifying attribute

optional_attribute

Optional attribute

Connectors

A |o--o| B

Zero or one

A ||--|| B

Eactly one

A }o--o{ B

Zero or many (“crows foot”)

A }|--|{

One or many

Example Entity Diagram

title Example Entity Relationship Diagram

entity Customer {
        first_name
        last_name
}

entity Address {
        street_1
        street_2
        city
        state
        postal_code
        country
}

entity Order {
        order_amount
        tax_amount
        shipping_amount
        total_amount
}

entity OrderItem {
}

entity Item {
        description
}

Customer }o--o{ Address
Order }o--o{ Customer
Order }o--|| Address : shipping
Order }o--o| Address : billing
Order ||--|{ OrderItem
OrderItem }o--|| Item

Class Diagrams

Lines

--

Solid line

..

Dotted line

Arrows

<|--, --|>

Extension

*--, --*

Composition

o--, --o

Aggregation

()--, --()

Lollipop (interfaces)

Vertical vs Horizontal Layout

--

Relationships with two dashes are laid out vertically

-

Relationships with one dash are laid out horizontally

Relations

Class A -- Class B

Relation

ClA -- ClB : label

Labeled relation

Driver - Car : drives >

<, > “acts on” label

Association Class

(Student, Course) .. Enrollment

Enrollment associates Student & Course

Fields & Methods

<ClassName> : <field>

Add a field to a class

<ClassName> : <method>()

Add a method to a class

class <ClassName> { (fields/methods) }

Define a class

Visibility

• - : private
• # : protected
• ~ : package private
• + : public

Abstract, Static, Stereotypes, annotation, enum

{static}

static modifier

{abstract}

Abstract modifer

<< name >>

Stereotype (interface)

enum

Define an enumeration

anootation

Define an annotation

Separators

==

Thick line

..

Dotted line

--

Plain line

__

Medium line

-- label --

Labeled line

Notes

note "text" as N1

Define a floating note; attach with ..

note left of <class>

Attach note above <class>

note right of <class>

Attach note right <class>

note top of <class>

Attach note top <class>

note bottom of <class>

Attach note bottom <class>

note <left|right|top|bottom> on link

Add a note to a link

Example Class Diagram

title Example Class Diagram

HumanDriver "1" -- Car : drives >
MachineDriver "1" -- Car : controls >

Car *- "4" Wheel : has >
note bottom on link #F9DEDE: TODO: change to # axles

Car --> HumanDriver : < owns

Driver ()-- HumanDriver

Driver ()-- MachineDriver

note as DISCLAIMER
	  Use flymode at your own risk.
	  Provided as-is.
end note

note top of Driver : Can be human or machine
abstract class Driver

class HumanDriver << Driver >> {
	  + name
	  + dob
	  + license
}

DISCLAIMER .. Car
class Car {
	  - internalSpecs
	  --
	  + color
	  + turn()
	  + accelerate()
	  + brake()
	  ..
	  + fly()
}

class Foo {
	  color
	  wheels
}