The UML diagrams architects still use

What UML is, and where it stands today

The Unified Modeling Language (UML) is a general-purpose graphical language for describing the structure and behaviour of software. It grew out of the merger, at Rational Software in the mid-1990s, of the methods of Grady Booch, James Rumbaugh and Ivar Jacobson, and was adopted as a standard by the Object Management Group (OMG), an industry standards consortium, in 1997. UML 2.0 (2005) was a major revision. The current version is UML 2.5.1, published by the OMG in December 2017; the earlier UML 2.4.1 was also published by ISO as ISO/IEC 19505 (2012). The specification defines fourteen diagram types, divided into structure diagrams (such as class, component and deployment diagrams) and behaviour diagrams (such as activity, state machine and sequence diagrams).

UML's reputation has changed considerably. In the late 1990s and early 2000s it was promoted as the basis of model-driven development, in which detailed models would be transformed into code. That ambition largely failed outside specialist domains, and many teams associate UML with heavyweight processes and diagrams nobody read. When Marian Petre interviewed 50 professional software developers for a study presented at ICSE 2013, 35 said they did not use UML at all and most of the others used it selectively and informally; most teams draw informal boxes and lines rather than strict UML. Yet a handful of UML diagram types remain the best tools available for particular questions, especially questions about behaviour over time, and their notation is widely understood. An architect does not need all fourteen diagram types; they need perhaps six, used deliberately.

This section covers those six, each with a small example from the food-delivery platform used throughout this chapter. It assumes the C4 vocabulary from Section 4.3; the two combine well, with C4 for the structural overview and UML where precision about interfaces, interactions or states pays for itself.

Sketch, blueprint or programming language

Martin Fowler's UML Distilled (3rd edition, Addison-Wesley, 2003) and his essays of the same year distinguish three ways of using UML, a classification Steve Mellor arrived at independently. As a sketch, UML is used informally and selectively to communicate ideas: on a whiteboard before writing code (forward sketching) or to explain part of an existing system (reverse sketching). Only the important elements appear, the notation is followed loosely, and the diagram is often thrown away. Fowler's own summary is comprehensiveness is the enemy of comprehensibility.

As a blueprint, UML is used to produce complete, precise models that someone else implements, or that are generated from existing code to document it in full; the point is completeness, and tools are usually needed. As a programming language, the UML model is detailed enough to be compiled into executable code, the goal of model-driven architecture (MDA). This mode survives in some embedded and safety-critical niches, often via specialised profiles and tools, but has not become mainstream.

For architects, sketch mode is the default and blueprint mode the exception. The useful question for each diagram is: who will read it, and what decision or understanding does it support? A sequence diagram sketched to agree how payment failures are handled is valuable even if it ignores half the notation. A full class model of a 200-class service, maintained by hand, is usually not.

Component diagrams: parts and their interfaces

A UML component diagram shows modular parts of a system and, above all, their interfaces. Its distinctive notation is the "ball and socket": a small circle on a stick (a provided interface, which the component offers) and a half-circle (a required interface, which it needs someone else to provide). When a ball sits in a socket, the two components are wired together through that interface. Dependencies are dashed arrows, optionally labelled with a stereotype such as «use».

This is exactly what architects care about when they want to show dependency direction and replaceability. In the example, the ordering component does not depend on the payment provider directly; it requires a PaymentPort interface, which a separate payment adapter implements. That is the dependency inversion and ports-and-adapters thinking of Chapter 3 made visible: swapping payment providers means writing a new adapter, not changing ordering. A C4 component diagram can show the same parts, but it does not distinguish provided from required interfaces.

Deployment diagrams: nodes and artifacts

A UML deployment diagram shows the physical or virtual infrastructure and what runs on it. Its elements are nodes, drawn as three-dimensional boxes, which are computational resources: a «device» such as a phone or server, or an «executionEnvironment» such as an operating system, a container runtime or a Kubernetes cluster, and nodes can be nested. Artifacts, drawn as rectangles with a document icon and the «artifact» stereotype, are the physical files deployed: a JAR, a container image, a mobile app bundle, a configuration file. Lines between nodes are communication paths, labelled with protocols.

Deployment diagrams are allocation views in the SEI's terms (Section 4.2). They answer the operations team's questions: where does each part run, how many copies, in which region, which network paths exist. C4's deployment diagram covers the same ground with less formal notation; either is fine as long as there is one per important environment and it shows replicas, managed services and network boundaries.

Sequence diagrams: who calls whom, in what order

If architects keep only one UML diagram, it is usually the sequence diagram. It shows how participants interact over time for one scenario. Participants appear across the top, each with a dashed vertical lifeline; time runs downwards. A thin rectangle on a lifeline, the activation (execution specification), shows when that participant is busy handling a message.

The arrowheads carry meaning. A synchronous message, where the sender waits for an answer, has a solid line and a filled arrowhead. A reply has a dashed line and an open arrowhead. An asynchronous message, where the sender carries on without waiting, has a solid line and an open arrowhead. Getting these right matters architecturally: whether the ordering service waits for the payment provider or publishes and moves on decides its latency, its failure modes and its coupling (see Section 0.6).

Combined fragments add control flow: a box labelled alt with guarded sections separated by a dashed line shows alternatives (if/else), opt shows an optional part, loop a repetition and par parallel sections. Use them sparingly; a sequence diagram with nested loops and alternatives is code drawn badly. Draw one diagram per important scenario, including the failure scenarios, which are where most of the architectural thinking happens.

State machine diagrams: lifecycles and rules

Many business objects have a lifecycle: an order, a payment, a subscription, an insurance claim. A state machine diagram describes it precisely. States are rounded rectangles; a filled circle marks the initial pseudo-state and a bullseye the final state. Transitions are arrows labelled event [guard] / action: the event that triggers the transition, an optional guard condition that must be true, and an optional action performed on the way. States can have internal behaviours such as entry / notify restaurant.

State machines are architectural more often than people expect. The order lifecycle below is shared by several services: ordering owns it, dispatch and notification react to its transitions, and support staff can trigger some of them. Agreeing on the states and the legal transitions, in one diagram, prevents a whole class of bugs in which one service thinks an order is cancelled while another dispatches a courier. The diagram also exposes questions that text hides: can an order be cancelled once it is out for delivery? (Here, no: there is no transition from that state to Cancelled.) Is a refund an action on a transition or a separate lifecycle?

Activity diagrams: workflows and parallelism

An activity diagram is a flowchart with precise semantics. Rounded rectangles are actions; diamonds are decisions (with guards on the outgoing flows) and merges; thick bars are forks, which split one flow into parallel flows, and joins, which wait for all incoming flows before continuing. Partitions, often called swimlanes, show who or what performs each action. A loop must flow back through a merge diamond: two flows drawn straight into one action would mean that the action waits for both, like a join.

Architects use activity diagrams for business processes and workflows that span several parts of a system, especially where parallelism and responsibility matter. The example shows that food preparation and courier assignment run in parallel, that assignment loops until a courier accepts, and that hand-over waits for both. That raises an architectural question immediately: what if no courier accepts within twenty minutes while the food is ready? The diagram makes the gap visible; the answer might be a timeout transition, a compensation step, or a change to the order lifecycle. Long-running workflows of this kind are often implemented as sagas or orchestrated workflows, covered in Chapter 6.

Class diagrams, used sparingly: the domain model

The class diagram is the best-known UML diagram and the one architects should use most sparingly. Drawing every class of a service by hand is the blueprint mode at its least useful: it is out of date within weeks and the code says the same thing more precisely. Where class diagrams earn their place is the domain model: a small diagram of the key business concepts, their attributes and their relationships, which developers, product managers and domain experts can discuss together. In domain-driven design terms (Chapter 5) it captures the ubiquitous language of one bounded context.

The essentials are few. A class box has a name, attributes and optionally operations. A plain line is an association, optionally named, with multiplicities at each end (1, 0..1, 0..*, 1..*). A filled diamond marks composition: the parts belong to exactly one whole and do not outlive it, as order lines belong to an order. A hollow triangle marks generalisation (inheritance) and a dashed line with an open arrowhead a dependency. Multiplicities carry real design decisions: Order 1 to 0..1 Delivery says an order has at most one delivery, which rules out splitting a large order between two couriers. If the business might want that, the diagram is where the question surfaces.

When UML is overkill, and when precision matters

UML is overkill when the audience does not know it and the question does not need it: a C4 context diagram communicates better to executives than a UML use case diagram, and a whiteboard sketch is the right tool for a design discussion that will be over in an hour. It is overkill when diagrams are maintained by hand that could be generated, and when strict notation is enforced in a sketch whose purpose is to explore. Fowler's observation that the precision added in UML 2 mostly serves blueprint and programming-language users, and burdens sketchers, still holds.

Precision pays when misunderstanding is expensive. Interfaces between companies are the clearest case: when the food-delivery company integrates with a payment provider or a large restaurant chain's ordering system, each side builds against the other's description and discovers mismatches only in testing or production. A precise sequence diagram of the payment flow, including timeouts, retries, idempotency keys and webhooks, attached to the interface specification, is cheap insurance. Regulated and safety-critical industries (medical devices, rail, aviation, automotive, some financial systems) often require design documentation that auditors can trace from requirements to implementation; formal UML or its systems-engineering relative SysML is common there. Concurrency and lifecycle rules shared by several teams, like the order states above, benefit from a notation that forces every transition to be stated. And outsourced or distributed development, where the people implementing a design cannot easily ask its author, needs descriptions that leave less to interpretation.