State machines

Use a state diagram when the reader needs to understand which lifecycle transitions are legal—not which service calls another or who performs a business task.

state "Payment lifecycle" {
  presentation {
    title: auto
    titleSubtitle: "Guarded lifecycle; retry policy is illustrative"
  }

  entry: initial "Start"
  pending: state "Pending"
  authorized: state "Authorized"
  failed: state "Failed"
  completed: final "Completed"
  abandoned: final "Abandoned"

  entry -> pending
  pending -> authorized "authorize [approved]"
  pending -> failed "authorize [declined]"
  failed -> pending "retry [attempts remain]"
  failed -> abandoned "abandon [limit reached]"
  authorized -> completed "capture"
}

Edit source — diagram updates live

Source

kdiagram 1

state "Order lifecycle" {
  presentation {
    title: auto
    titleSubtitle: "Legal statuses after checkout. Guards are illustrative."
    showKindSubtitles: false
  }
  layout {
    direction: LR
    density: compact
    spacingScale: 1
    considerModelOrder: true
  }
  edges {
    route: orthogonal
    crossings: gaps
  }

  entry: initial
  placed: state "Placed" { styles: ["info"] }
  authorized: state "Authorized"
  reserved: state "Reserved"
  shipped: final "Shipped" { styles: ["success"] }
  abandoned: final "Abandoned" { styles: ["warning"] }
  cancelled: final "Cancelled" { styles: ["muted"] }

  entry -> placed
  placed -> authorized "approved"
  placed -> abandoned "declined"
  authorized -> reserved "in stock"
  authorized -> cancelled "cancel"
  reserved -> shipped "ship"
  reserved -> cancelled "cancel"
}

initial renders as a filled pseudostate and final as a double-ring terminal. Kekonic Diagrams reports structured diagnostics for missing or duplicate initial states, incoming transitions to initial, and outgoing transitions from final states.

Use junction, fork, and join only when they express real transition structure. Labels should name the trigger and, when relevant, a guard in square brackets. Kekonic Diagrams validates structural state-machine invariants but does not execute UML actions, concurrency, or guard expressions.

Dense compensation, return, and administrative paths often deserve a separate recovery state view. Render-quality warnings identify extreme canvases, canvas-spanning edges, crossings, reverse-flow pressure, and excessive edge-label density.