# PlantUML Diagram Types

The eight diagrams the Confluence page author reaches for, with the
PlantUML skeleton for each. Pick the type by what the reader needs to
*do* with the diagram, not by what the data looks like.

| Reader needs | Pick |
|--------------|------|
| Trace a request across actors | sequence |
| Show who owns which service | component |
| Show static structure / inheritance | class |
| Show valid states of one object | state |
| Show branching workflow | activity |
| Show deployment topology | deployment |
| Show signal timing / concurrency | timing |
| Show domain entities | ER |

## Sequence

```
@startuml
participant Client
participant Service
participant DB

Client -> Service: request
Service -> DB: query
DB --> Service: rows
Service --> Client: response
@enduml
```

## Component

```
@startuml
[Web] --> [API]
[API] --> [DB]
[API] --> [Cache]
@enduml
```

For C4, prefer hand-drawn boxes if the BASS PlantUML plugin doesn't ship the
`C4_Container` stdlib. Test with one diagram before committing to the
notation.

## Class

```
@startuml
class Order {
  +id: UUID
  +status: Status
  +total(): Money
}
class LineItem {
  +sku: string
  +qty: int
}
Order "1" *-- "*" LineItem
@enduml
```

## State

```
@startuml
[*] --> Draft
Draft --> Submitted: submit
Submitted --> Approved: approve
Submitted --> Rejected: reject
Approved --> [*]
Rejected --> [*]
@enduml
```

## Activity

```
@startuml
start
:parse input;
if (valid?) then (yes)
  :process;
else (no)
  :reject;
  stop
endif
:persist;
stop
@enduml
```

## Deployment

```
@startuml
node "k8s prod" {
  [service-a] --> [service-b]
}
node "external" {
  [IdP]
}
[service-a] --> [IdP]
@enduml
```

## Timing

```
@startuml
robust "Client" as C
robust "Service" as S
C is Idle
S is Idle
@0
C is Requesting
@5
S is Processing
@10
S is Idle
C is Idle
@enduml
```

## ER

```
@startuml
entity "Order" {
  *id : UUID
  --
  total : Money
}
entity "LineItem" {
  *id : UUID
  --
  sku : string
  qty : int
}
Order ||--o{ LineItem : contains
@enduml
```

## What is NOT a use case

If the diagram needs prose between boxes, it is not a use case. Use a
sequence or activity diagram instead.

## When to use multiple diagrams

A page that needs two diagrams is fine. A page that needs five is a wall
 — split the page.
