Class and state diagrams
Architecture diagrams show a system from above (high-level design). Class and state diagrams zoom in on one part of it (low-level design): how the code is structured, and how one thing moves through its life.
Class diagrams
diagram class "Ordering"
class Order {
+ id: UUID
- items: List<Item>
+ total(): Money
+ pay(method: PaymentMethod): Receipt
}
interface Payable {
+ pay(amount: Money): Receipt
}
abstract class Vehicle {
# wheels: int
}
enum Status { OPEN; PAID; SHIPPED }
class Item
class Customer
class Car
class Payment
class Logger
Order *-- Item from="1" to="1..*" : contains
Order o-- Customer
Car --|> Vehicle
Order ..|> Payable
Order --> Payment : uses
Order ..> LoggerKinds: class, interface, abstract class, enum, and package name { … } to group them.
Rows inside a class are fields and methods, one per line (or separated by ;): [+|-|#|~] name[: type] for a field, [+|-|#|~] name(params)[: type] for a method. The symbol is the visibility: + public, - private, # protected, ~ package. {static} and {abstract} may follow. An enum lists plain values.
Relations:
| Arrow | Meaning | Drawn as |
|---|---|---|
--|> | inheritance (extends) | solid line, hollow triangle |
..|> | realisation (implements) | dashed line, hollow triangle |
*-- | composition (owns, same lifetime) | filled diamond at the owner |
o-- | aggregation (has) | hollow diamond at the owner |
--> | directed association (uses) | solid line, open arrow |
-- | association | solid line |
..> | dependency | dashed line, open arrow |
Multiplicity goes in from="…" and to="…" and is drawn next to each end. Class diagrams lay out top to bottom, so parents sit above their children.
State diagrams
diagram state "Order lifecycle"
start s
state draft "Draft"
state review "In review"
state paid "Paid"
choice ok
end done
composite fulfilment "Fulfilment" {
state picking "Picking"
state shipped "Shipped"
picking -> shipped : dispatched
}
s -> draft
draft -> review : submit [items > 0] / notify reviewer
review -> ok
ok -> paid : [approved]
ok -> draft : [rejected]
paid -> fulfilment
fulfilment -> doneKinds: start (filled dot), end (ringed dot), state (rounded box), choice (diamond), fork and join (bars), and composite name "Label" { … } for a state with states inside.
Transitions use the UML label form event [guard] / action; every part is optional. The guard and action are styled so they stand out from the event. A state may transition to itself.
State diagrams lay out left to right.
When to use which
- Class diagram: before writing or reviewing a module, to agree on the types and who owns what. Template: "Parking lot" (
ink init --template parking-lot). - State diagram: for anything with a status field, such as orders, tickets, payments or subscriptions, to make every allowed transition explicit. Template: "Order lifecycle" (
ink init --template order-lifecycle). - Sequence diagram (available now): for the order of calls in one request.