Learn UML

A practical introduction to the Unified Modeling Language, covering every diagram type UML Wizard draws.

What is UML?

The Unified Modeling Language (UML) is a standard set of diagrams for describing software: what it is made of, how its parts talk to each other, and how it behaves. It is maintained by the Object Management Group (OMG); UML Wizard follows UML 2.5.1 notation.

UML diagrams fall into two families:

Structure diagrams show what a system is: its parts and how they relate. UML Wizard draws class, component and deployment diagrams.
Behaviour diagrams show what a system does: over time, in response to events, or for its users. UML Wizard draws sequence, state machine, activity and use case diagrams.

You don't need every diagram for every project. Draw the one that answers the question you have, and leave out the detail that doesn't help answer it: a diagram is a way of communicating, not a complete copy of the code.

Every example on this page comes from the OnlineShop sample project (samples/OnlineShop/OnlineShop.umlwiz). Open it alongside this page to explore the diagrams in UML Wizard.

Class diagrams

The question it answers: what kinds of things are in my system, what do they know and do, and how are they connected? Class diagrams are the most widely used UML diagram, and the one UML Wizard can turn into code.

Based on Ordering → Domain Model in the OnlineShop sample.

Classes

A class is a box with up to three compartments: its name, its attributes (the data it holds) and its operations (what it can do).

An attribute is written visibility name: Type = default, e.g. -status: OrderStatus = New.
An operation is written visibility name(parameter: Type, …): ReturnType, e.g. +total(): decimal.
Visibility says who may use a member: + public (anyone), - private (the class itself), # protected (the class and its subclasses), ~ package (classes in the same package).
Static members, which belong to the class rather than to each object, are underlined.
An abstract class or operation is written in italics. An abstract class can't be created on its own; it exists to be specialized, like Entity above.

Two special kinds of class carry a stereotype in guillemets above the name:

An «interface» is a contract: a set of operations that classes promise to provide, with no implementation of its own (IPayable).
An «enumeration» is a fixed list of named values, its literals (OrderStatus: New, Paid, Shipped).

You can write your own stereotype, such as «aggregate root» or «entity», to say what role a class plays.

In UML Wizard: use the Class, Abstract, Interface and Enum tools, then double-click a class to edit its name, stereotype, attributes and operations.

Relationships

Relationship	Drawn as	Means	Tool
Association	Solid line	The classes know about each other: “a Customer places Orders”.	Association
Directed association	Solid line, open arrowhead	Only one side knows the other: the arrow points to the class that is referenced.	Directed
Aggregation	Solid line, hollow diamond at the whole	“Has a”: a whole groups parts that can also exist without it (a team and its players).	Aggregation
Composition	Solid line, filled diamond at the whole	“Is made of”: the parts belong to exactly one whole and live and die with it (an order and its lines).	Composition
Generalization	Solid line, hollow triangle at the general class	“Is a kind of”: inheritance. A Customer is a kind of Entity.	Inheritance
Realization	Dashed line, hollow triangle at the interface	“Implements”: the class provides the interface's operations.	Realization
Dependency	Dashed line, open arrowhead	“Uses”: a weaker, often temporary, link, e.g. a parameter type.	Dependency

Diamonds sit at the whole; triangles and arrowheads point to the class being specialized, implemented or used.

Multiplicity

The numbers at each end of an association say how many objects take part. Read them from the far side: “one Customer places 0..* Orders”, “an Order has 1..* OrderLines”.

Multiplicity	Means
`1`	exactly one
`0..1`	optional: none or one
`` or `0..`	any number, including none
`1..*`	at least one
`2..4`	a range

In UML Wizard: double-click a relationship to set its label and the multiplicity at each end.

Common mistakes

Arrows backwards. Generalization and realization point from the specific class to the general one or the interface: the subclass knows its parent, not the other way round.
Composition everywhere. Use composition only when the part can't exist without the whole. A Customer isn't composed of Orders: deleting a customer record doesn't make the orders never have happened.
Diamond at the wrong end. The diamond sits next to the whole (Order), not the part (OrderLine).
An attribute and an association for the same thing. If Order has an association to OrderLine, don't also list -lines: List<OrderLine> as an attribute; the association already says it.
Too much detail. Leave out getters, setters and obvious members unless they matter to the reader.

Sequence diagrams

The question it answers: for one scenario, who calls whom, and in what order? Sequence diagrams are ideal for explaining a single flow through the system, such as checking out.

Based on Ordering → Checkout Sequence. Time runs downwards.

Lifelines

Each participant is a lifeline: a head with a dashed line hanging below it. The head names an object as name : Type (shop : ShopController); either part may be left out. A stick figure is an actor, someone or something outside the system, such as the customer.

In UML Wizard: Lifeline and Actor add participants.

Messages

Messages are arrows between lifelines, read from top to bottom. The label is the call, usually with its arguments.

Message	Drawn as	Means	Tool
Synchronous	Solid line, filled arrowhead	A call: the sender waits for it to finish.	Sync
Asynchronous	Solid line, open arrowhead	A signal: the sender carries on without waiting (an email, an event, a queue message).	Async
Reply	Dashed line, open arrowhead	The return from a synchronous call, labelled with what is returned.	Reply
Create	Dashed line to the head of a new lifeline, «create»	The sender creates the receiver; its lifeline starts there.	Create

Common mistakes

Mixing up sync and async. If the sender needs the answer before going on, it's synchronous.
A reply for every call. Replies are optional; draw them when the returned value matters to the story.
Trying to show every branch. A sequence diagram tells one scenario. Draw a second diagram for the failure case, or use an activity diagram for the decisions.
Too many lifelines. More than six or seven participants usually means the diagram should be split.

State machine diagrams

The question it answers: what states can one thing be in, and what moves it from one to the next? They suit anything with a lifecycle: an order, a document, a connection, a user account.

Simplified from Ordering → Order Lifecycle.

States and pseudostates

A state is a rounded rectangle: a situation the thing stays in until something happens (Created, Paid). Name states with adjectives or past participles, not actions.
The initial pseudostate, a filled circle, marks where the machine starts. There is one per state machine.
A final state, a circle around a dot, means the machine has finished. There may be several.
A choice, a small diamond, splits one transition into several; each outgoing transition has a guard.

Transitions

An arrow from one state to the next, labelled trigger [guard] / effect. All three parts are optional:

The trigger is the event that fires it: pay, cancel, delivered.
The guard, in square brackets, is a condition that must be true: [in stock].
The effect, after a slash, is what happens on the way: / capture(), / refund().

A transition can return to the state it left (a self-transition, like edit above): the event is handled but the state doesn't change.

In UML Wizard: the Initial, Final and choice tools add pseudostates; drag with the transition tool from one state to the next, or back onto the same state.

Common mistakes

States that are really actions. “Calculate total” is an action; the state is what the thing is while or after it happens.
Guards that leave gaps. The guards after a choice should cover every case; add an [else] branch if needed.
Dead ends. Check that every state other than a final one has a way out, and that every state can be reached.

Activity diagrams

The question it answers: what steps happen, in what order, with which decisions and which steps in parallel? Activity diagrams are UML's flowcharts, good for business processes and algorithms.

Based on Ordering → Checkout Process.

Nodes and flows

Element	Drawn as	Means
Action	Rounded rectangle	One step of work. Name it with a verb: Charge payment.
Initial node	Filled circle	Where the activity starts.
Activity final	Circle around a dot	The whole activity ends, even if other paths are still running.
Decision	Diamond, one flow in, several out	Exactly one outgoing flow is taken, chosen by its guard.
Merge	Diamond, several flows in, one out	Alternative paths come back together.
Fork	Bar, one flow in, several out	The outgoing flows run in parallel.
Join	Bar, several flows in, one out	Waits until all incoming flows have arrived.
Control flow	Arrow, with an optional guard such as `[guest]`	What happens next.

In UML Wizard: use the action, Initial, Final, decision and Fork/Join tools, and connect them with Flow. Drag the corner handle of a fork/join bar to make it longer or vertical.

Common mistakes

Using a merge where a join is needed. After a fork, bring the parallel paths together with a join bar. A merge diamond doesn't wait, so the step after it would run twice.
Unlabelled decisions. Every flow leaving a decision needs a guard, and together they should cover every case.
Mixing levels of detail. Keep the actions at a similar level: “Check out” next to “Increment counter” is confusing.

Use case diagrams

The question it answers: who uses the system, and what can they do with it? Use case diagrams give a one-page overview of the requirements, readable by people who aren't developers.

Simplified from Requirements → Shop Use Cases.

Elements

An actor (stick figure) is a role played by a person or another system, outside the system: Customer, Payment Provider. Name the role, not the person.
A use case (ellipse) is something an actor wants to achieve with the system, named as a goal: Place order, not Order page.
The system boundary (rectangle) shows what is inside the system. Actors stay outside it.

Relationships

Relationship	Drawn as	Means
Association	Solid line	The actor takes part in the use case.
«include»	Dashed arrow from the base use case to the included one	The base always does the included behaviour: placing an order always involves paying.
«extend»	Dashed arrow from the extension to the base use case	The extension sometimes adds to the base: applying a coupon is optional.
Generalization	Hollow triangle at the general actor or use case	A specialized version: a Member is a Customer who can do more.

In UML Wizard: use the Actor, Use Case and System tools. Use cases inside a system boundary move with it.

Common mistakes

«extend» drawn the wrong way. The arrow points to the use case being extended, the opposite of «include».
Use cases as steps. “Enter password” and “Click submit” are steps of a use case, not use cases. Ask: would the actor be satisfied if only this happened?
Turning it into a flowchart. Use case diagrams have no order. For the sequence of steps, use an activity or sequence diagram.

Component diagrams

The question it answers: what are the big, replaceable building blocks of the system, and through which interfaces do they depend on each other? Component diagrams show the architecture above the level of classes.

Simplified from Architecture → Shop Components.

Elements

A component is a self-contained, replaceable part of the system with a clear job: a service, a library, a front end. It is drawn as a box with «component» and a small component icon.
A provided interface (the “lollipop”, a circle on a line) is a service the component offers to others. The line from the component to the interface is a realization.
A dependency (dashed arrow) shows that one component needs another, or needs an interface. Pointing it at an interface rather than a component keeps the parts replaceable: anything that provides IPayments would do.

In UML Wizard: add components and interfaces, then connect a component to the interface it provides with a realization, and the components that need it with a dependency. Label a dependency with how it's used, e.g. HTTPS.

Common mistakes

One component per class. Components are coarse-grained: think deployable services, modules or libraries, not individual classes.
Dependencies straight to the implementation. Depend on interfaces where you can; it shows where parts could be swapped.
Cycles. If two components depend on each other, consider whether they are really one component, or whether an interface should break the cycle.

Deployment diagrams

The question it answers: where does the software run? Deployment diagrams show the machines, runtimes and files, and how the machines are connected.

Simplified from Architecture → Shop Deployment.

Elements

Element	Drawn as	Means
Node	3-D box	A computational resource that software runs on.
Device	3-D box with «device»	A physical machine: a server, a PC, a phone.
Execution environment	Box with «executionEnvironment», usually inside a node	Software that hosts other software: an operating system, a container runtime, a web server, a database engine.
Artifact	Box with «artifact» and a document icon	A concrete file that gets deployed: a program, a library, a script, a database file.
Communication path	Solid line between nodes, labelled with the protocol	The nodes can talk to each other: `HTTPS`, `gRPC`, `TCP 5432`.
«deploy»	Dashed arrow from an artifact to a node	The artifact is installed on the node. Placing the artifact inside the node says the same thing.
«manifest»	Dashed arrow from an artifact to a component	The file is the physical form of a component: `orders.dll` manifests Order Service.

In UML Wizard: nodes, devices and execution environments contain whatever you place inside them, and move it along when they move. Connect nodes with Path and label it with the protocol.

Common mistakes

Mixing up components and artifacts. A component is a logical part of the design; an artifact is the file that implements it. Link them with «manifest».
Unlabelled paths. The protocol (and port, if it matters) is usually the most useful thing on the line.
Every machine drawn. Show one node for a group of identical servers and say how many in its name or a note.

Notes and text boxes

Every diagram type can have notes: UML's comments, drawn as a rectangle with a folded corner and linked to what they describe by a dashed line. Use a note for something the notation can't say, such as “Refunds are issued within 5 working days.” on the Cancelled state.

In UML Wizard: add a note with Note and link it with Attach Note. Notes attached to a class become its documentation comment when you generate code. A Text Box is a free label, such as a title or a legend; unlike a note it isn't part of the UML model.

Where to go next

Open the OnlineShop sample and compare each diagram with the sections above.
The GangOfFour sample (samples/GangOfFour/GangOfFour.umlwiz) has a class diagram for each classic design pattern: a good way to practise reading class diagrams.
How to Generate Code: turn a class diagram into C#, Java, Kotlin, TypeScript, Ruby or C++.
How to Import and Export OpenAPI: turn a class diagram into a web API description, and back.
How to Import and Export PlantUML: exchange any diagram with PlantUML text.

UML Wizard draws a practical subset of UML 2.5.1. Constructs such as packages, combined fragments (alt, loop) in sequence diagrams, composite states and swimlanes aren't available. Help → About UML Wizard shows the supported UML version.