Class & State Diagrams

Class diagrams

Class diagrams model the static structure of a system: its types, members, and the relationships between them.

Basic class syntax

<div class="dp-mermaid language-mermaid">classDiagram class Animal { +String name +int age +makeSound() void +move(distance int) bool }</div>

Members are listed inside { }. Fields list type then name; methods add parentheses and an optional return type.

Member visibility

Symbol	Visibility
`+`	Public
`-`	Private
`#`	Protected
`~`	Package / internal

Append $ to mark a member as static, or * to mark it as abstract:

<div class="dp-mermaid language-mermaid">classDiagram class Repository { -String connectionString +$getInstance() Repository +*findById(id int) Entity #validate(entity Entity) bool }</div>

Relationships

<div class="dp-mermaid language-mermaid">classDiagram Animal <|-- Dog : Inheritance Car *-- Engine : Composition Car o-- Wheel : Aggregation Driver --> Car : Association Order ..> Product : Dependency Service ..|> IService : Realization</div>

Syntax	Relationship
`A <\|-- B`	B inherits from A (generalization)
`A *-- B`	A is composed of B (composition)
`A o-- B`	A aggregates B (aggregation)
`A --> B`	A has an association to B
`A -- B`	Link (undirected)
`A ..> B`	A depends on B
`A ..*`	Composition via dotted
`A ..\|> B`	A realizes interface B

All relationships can be reversed by swapping the symbols.

Cardinality labels

Add cardinality to either end of a relationship:

<div class="dp-mermaid language-mermaid">classDiagram class Customer { +String name } class Order { +Date placedAt } class LineItem { +int quantity } Customer "1" --> "0..*" Order : places Order "1" *-- "1..*" LineItem : contains</div>

Common cardinality strings: 1, 0..*, 1..*, 0..1, n, 1..n.

Relationship labels

Add a label after the relationship using : with a quoted or unquoted string:

<div class="dp-mermaid language-mermaid">classDiagram User "1" --> "0..*" Session : has Session --> Token : carries</div>

Annotations

Annotations mark the stereotype of a class. Place them inside the class body with <<...>>:

<div class="dp-mermaid language-mermaid">classDiagram class IRepository { <<Interface>> +findById(id int) Entity +save(entity Entity) void } class BaseService { <<Abstract>> +#validate() bool } class Status { <<Enumeration>> PENDING ACTIVE CLOSED } class UserService { <<Service>> }</div>

Common annotations: <<Interface>>, <<Abstract>>, <<Enumeration>>, <<Service>>, <<Repository>>, <<Component>>.

Namespaces

Group related classes inside a named namespace:

<div class="dp-mermaid language-mermaid">classDiagram namespace Domain { class User { +String email } class Order { +Date createdAt } } namespace Infrastructure { class UserRepository { +findByEmail(email String) User } } UserRepository --> User : returns</div>

Class diagram direction

Control layout with a leading direction declaration:

<div class="dp-mermaid language-mermaid">classDiagram direction LR class A class B A --> B</div>

Accepted values: TB, BT, LR, RL.

State diagrams

State diagrams model the lifecycle of an object — which states it can be in and the transitions between them.

Basic transitions

<div class="dp-mermaid language-mermaid">stateDiagram-v2 [*] --> Idle Idle --> Loading : fetch() Loading --> Success : ok Loading --> Error : fail Error --> Idle : reset() Success --> [*]</div>

[*] is the special initial / final state marker. A transition out of [*] is the entry; a transition into [*] is the exit.

State descriptions

Add a description to a state using state_id : description:

<div class="dp-mermaid language-mermaid">stateDiagram-v2 Idle : Waiting for user input Loading : Request in flight Success : Data received Error : Render error boundary [*] --> Idle Idle --> Loading Loading --> Success Loading --> Error</div>

Named states

Give a long-form display name to a state using state "label" as id:

<div class="dp-mermaid language-mermaid">stateDiagram-v2 state "Fetching data" as loading state "Render complete" as done [*] --> loading loading --> done : ok loading --> [*] : error</div>

Composite (nested) states

A composite state groups sub-states inside state id { ... }:

<div class="dp-mermaid language-mermaid">stateDiagram-v2 [*] --> Auth state Auth { [*] --> Unauthenticated Unauthenticated --> Authenticating : login() Authenticating --> Authenticated : success Authenticating --> Unauthenticated : failure Authenticated --> [*] } Auth --> App</div>

Fork and join

Model parallel execution with <<fork>> and <<join>>:

<div class="dp-mermaid language-mermaid">stateDiagram-v2 [*] --> fork state fork <<fork>> fork --> Logging fork --> Notifying Logging --> join Notifying --> join state join <<join>> join --> [*]</div>

Choice (conditional)

Branch based on a condition with <<choice>>:

<div class="dp-mermaid language-mermaid">stateDiagram-v2 [*] --> Validate Validate --> check state check <<choice>> check --> Success : valid check --> Error : invalid Success --> [*] Error --> [*]</div>

Concurrency

Split a composite state into concurrent regions with --:

<div class="dp-mermaid language-mermaid">stateDiagram-v2 [*] --> Active state Active { [*] --> UI UI --> UI : interaction -- [*] --> Sync Sync --> Syncing : timer Syncing --> Sync : done } Active --> [*] : logout</div>

Notes

Annotate a state with a free-form note:

<div class="dp-mermaid language-mermaid">stateDiagram-v2 [*] --> Idle note right of Idle Default state on startup. Re-entered after any reset. end note Idle --> Running</div>

Direction

<div class="dp-mermaid language-mermaid">stateDiagram-v2 direction LR [*] --> A --> B --> [*]</div>

Rendering with @domphy/mermaid

import { renderMermaidToSvg } from "@domphy/mermaid"

const classSvg = await renderMermaidToSvg(`classDiagram
  class IStore {
    <<Interface>>
    +get(key String) T
    +set(key String, value T) void
  }
  class RecordState {
    +get(key String) T
    +set(key String, value T) void
  }
  IStore <|.. RecordState : implements`, { theme: "neutral" })

const stateSvg = await renderMermaidToSvg(`stateDiagram-v2
  [*] --> Idle
  Idle --> Loading : query.fetch()
  Loading --> Success : data received
  Loading --> Error : network fail
  Error --> Idle : retry()
  Success --> [*]`, { theme: "neutral" })

Class & State Diagrams#

Class diagrams#

Basic class syntax#

Member visibility#

Relationships#

Cardinality labels#

Relationship labels#

Annotations#

Namespaces#

Class diagram direction#

State diagrams#

Basic transitions#

State descriptions#

Named states#

Composite (nested) states#

Fork and join#

Choice (conditional)#

Concurrency#

Notes#

Direction#

Rendering with @domphy/mermaid#