Inkline
Menu
Docs / Reference

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 ..> Logger
Ordering 9 items and 6 connections. contains11..* uses Order+id: UUID−items: List<Item>+total(): Money+pay(method: PaymentMethod): Receipt «interface»Payable+pay(amount: Money): Receipt Item Customer Payment Logger «abstract»Vehicle#wheels: int Car «enumeration»StatusOPENPAIDSHIPPED
Ordering, drawn from the text above

Kinds: 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:

ArrowMeaningDrawn 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
--associationsolid line
..>dependencydashed 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 -> done
Order lifecycle 8 items and 8 connections. Fulfilment dispatched submit [items > 0] / notifyreviewer [approved] [rejected] Draft In review Paid Picking Shipped
Order lifecycle, drawn from the text above

Kinds: 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.