UML Tutorial: Learn Modeling from Scratch (2026)
Unified Modeling Language (UML) is a standardized visual notation for specifying, constructing, and documenting software systems. Over years of architecting enterprise applications, I have used UML to communicate design decisions across teams, uncover flaws before writing code, and document complex systems for new team members. This tutorial covers 14 UML diagram types organized into structure diagrams (showing static relationships) and behavior diagrams (showing dynamic interactions).
We will focus on the most widely used diagrams: class diagrams for domain modeling, sequence diagrams for interaction patterns, use case diagrams for requirements capture, and activity diagrams for workflow modeling. Each diagram type is presented with notation rules, common patterns, and practical examples drawn from real systems.
Class Diagrams: Structure and Relationships
Class diagrams are the backbone of UML, showing classes, attributes, operations, and relationships. A class is drawn as a rectangle with three compartments: name, attributes (visibility: type = default), and operations. Relationships include association (solid line, simple connection), aggregation (hollow diamond, part-of with independent lifecycle), composition (filled diamond, part-of with dependent lifecycle), inheritance (hollow triangle, also called generalization), and dependency (dashed arrow, usage without structural relationship). Multiplicity notations (1, 0..*, 1..*) specify cardinality at each end.
+-------------------+ +-------------------+
| Customer | | Order |
+-------------------+ +-------------------+
| - id: int | | - id: int |
| - name: String | | - date: Date |
| - email: String | | - total: double |
+-------------------+ +-------------------+
| + placeOrder() |<>---- | + addItem() |
| + getHistory() |1 | + calculateTotal()|
+-------------------+ * +-------------------+
| |
* 1
+-----------+ +-----------+
| OrderItem | | Product |
+-----------+ +-----------+
| - qty: int| | - sku: str|
| - price | | - name |
+-----------+ +-----------+
# Conceptual code mapping
class Customer:
def placeOrder(self) -> Order: pass
class Order:
items: List[OrderItem]
def calculateTotal(self) -> float: passSequence Diagrams: Interaction Over Time
Sequence diagrams show how objects interact in chronological order. Lifelines (dashed vertical lines) represent participants. Activation bars on lifelines show when an object is active. Messages (horizontal arrows) between lifelines represent method calls. Return messages are dashed arrows. Combined fragments with interaction operators express control flow: alt (alternatives/if-else), opt (optional), loop (iteration), par (parallel), and ref (reference to another diagram). Sequence diagrams excel at documenting single scenarios through a specific code path.
# Sequence diagram as text (PlantUML style)
@startuml
actor User
participant "WebApp" as App
participant "AuthService" as Auth
database "UserDB" as DB
User -> App: POST /login(credentials)
App -> Auth: authenticate(email, pass)
Auth -> DB: SELECT * FROM users WHERE email=?
DB --> Auth: user_row
Auth -> Auth: verify_password(hash, pass)
alt success
Auth -> App: token=JWT(...)
App -> User: 200 {token}
else failure
Auth -> App: error="Invalid credentials"
App -> User: 401 Unauthorized
end
@enduml
# Implemented as:
def login_handler(request):
user = db.query("SELECT * FROM users WHERE email=?", request.email)
if user and verify_password(user.hash, request.password):
return jsonify(token=create_jwt(user.id))
return abort(401)Use Case Diagrams: Requirements at a Glance
Use case diagrams capture functional requirements from an end-user perspective. Actors (stick figures) represent roles users or external systems play. Use cases (ovals) represent functional goals. System boundary (rectangle) delimits the system scope. Relationships include association (line connecting actor to use case), extend (dashed arrow with «extend», optional behavior inserted at extension points), include (dashed arrow with «include», mandatory sub-behavior), and generalization (hollow triangle, specialized actor or use case). A well-crafted use case diagram communicates scope to stakeholders without technical jargon.
# Use case diagram (textual representation)
# System: Online Banking Portal
+---------------------------+
| Online Banking |
| +--------+ +---------+ |
| | View | | Transfer| |
| |Balance | | Funds | |
| +--------+ +---------+ |
| ^ ^ |
| |<>| |
| | | |
| +-------------------+ |
| | Authenticate User | |
| +-------------------+ |
| ^ |
+----------------------------+
|
(Customer)---(Admin)
|
+------------------+
| Fraud Detection |
| System (external) |
+------------------+
# Each use case expands to a detailed step-by-step description Activity Diagrams: Workflow and Flow Control
Activity diagrams model workflows as sequences of actions connected by edges, similar to flowcharts but with support for concurrency. Initial node (filled circle) starts the flow. Action nodes (rounded rectangles) represent atomic steps. Decision nodes (diamond) branch based on guard conditions. Fork/join nodes (thick bars) split and synchronize concurrent flows. Swimlanes partition activities by responsibility. Activity diagrams are ideal for modeling business processes, algorithm workflows, and use case scenarios that involve multiple actors or parallel execution.
# Activity diagram as text
@startuml
|Customer|
start
:Browse Catalog;
:Add Item to Cart;
|System|
:Validate Cart;
fork
:Check Inventory;
:Calculate Shipping;
:Apply Discounts;
fork again
:Process Payment;
endfork
|Customer|
if (Payment successful?) then (yes)
:Show Confirmation;
:Send Email Receipt;
else (no)
:Show Error Message;
endif
stop
@enduml
# Activity diagram behaviors can be directly translated to code
# using state machines or workflow enginesState Machine Diagrams: Lifecycle Modeling
State machine diagrams model the lifecycle of a single object, showing states, transitions, events, and actions. A state (rounded rectangle) represents a stable condition. Transitions (arrows) between states are triggered by events with optional guard conditions. Actions can occur on entry (entry/), exit (exit/), or during a transition (do/). Composite states contain nested substates. History pseudo-states (H, H*) resume the last active substate. State diagrams are essential for modeling UI navigation, protocol handlers, and object lifecycles in domain-driven design.
# Order state machine
@startuml
[*] -> PENDING
PENDING --> CONFIRMED : payment_received
PENDING --> CANCELLED : cancel_request
CONFIRMED --> SHIPPED : ship
CONFIRMED --> CANCELLED : cancel_before_ship (if allowed)
SHIPPED --> DELIVERED : confirm_delivery
SHIPPED --> RETURNED : return_request
DELIVERED --> CLOSED : auto_close_after_30d
RETURNED --> REFUND_ISSUED : issue_refund
REFUND_ISSUED --> CLOSED : complete
@enduml
# Implementation pattern
class OrderState:
def handle(self, event): pass
class PendingState(OrderState):
def handle(self, event):
if event == 'payment_received':
return ConfirmedState()
elif event == 'cancel_request':
return CancelledState()Deployment and Component Diagrams
Deployment diagrams show the physical architecture: nodes (3D boxes) represent hardware or execution environments, connected by communication paths (lines). Artifacts (files, executables, scripts) are deployed to nodes. Component diagrams show the logical architecture of software components — their interfaces, ports, and wiring. Components are larger than classes (e.g., microservices, libraries, databases). Provided interfaces (lollipop symbol) and required interfaces (socket symbol) connect components via assembly connectors. These diagrams bridge the gap between architecture and operations.
# Deployment diagram (textual representation)
+---------------------+ +---------------------+
| Web Server | | Application Server|
| (AWS EC2 t3.large) | | (AWS EC2 t3.xlarge) |
| +---------------+ | | +---------------+ |
| | nginx:1.24 | | | | gunicorn:app | |
| | reverse proxy | | | | REST API | |
| +---------------+ | | +---------------+ |
+----------+----------+ +---------+----------+
| http/2 | gRPC
| +-------------+----------+
| | Database Server |
+--------------| (AWS RDS db.r5.large) |
| +------------------+ |
| | PostgreSQL 16 | |
| | +-------------+ | |
| | | orders_db | | |
| | +-------------+ | |
| +------------------+ |
+------------------------+
# Component diagram parallels the deployment but focuses on interfaces
# e.g. WebServer component requires HTTP interface, AppServer provides itFrequently Asked Questions
What is the difference between aggregation and composition in UML?
Both represent whole-part relationships. Aggregation (hollow diamond) means the part can exist independently (a Department has Students — students can exist without the department). Composition (filled diamond) means the part's lifecycle depends on the whole (an Order has OrderItems — items are destroyed when the order is deleted).
When should I use a sequence diagram vs an activity diagram?
Use sequence diagrams to show fine-grained message passing between objects over time, especially for a single scenario. Use activity diagrams for broad workflows with parallel flows, business processes, and swimlane-based responsibility assignment across multiple actors.
Is UML still relevant in the age of agile development?
Yes, but used selectively. Agile teams use UML for communicating complex designs that are hard to convey in text — class diagrams for domain models, sequence diagrams for tricky interactions. The key is to keep diagrams simple and focused, not to create comprehensive documentation upfront.
How do I choose between the 14 UML diagram types?
Start with class diagrams (static structure), use case diagrams (scope), and sequence diagrams (behavior). Add state machine diagrams for objects with complex lifecycles, activity diagrams for workflows, and deployment diagrams for distributed systems. Use the rest as needed for specific concerns.
Originally published on Ayodhyyya. Last updated June 1, 2026.