Notation, explained
Every diagram, explained
Four notations - UML, ArchiMate, BPMN and ER - with one article per diagram kind, every one of them carrying real diagrams rather than descriptions of diagrams. Start with a series or jump to the one you need.
Start here
What is UML?
The Unified Modeling Language in practice: the fourteen diagram types, how structure and behaviour split, and how to pick the right diagram for the question you are actually asking.
14 min read
Read in order
Every UML diagram, explained
Fourteen diagram types in UML 2.5.1, one article each, every one of them with real diagrams rather than descriptions of diagrams.
- Foundations01
What is UML?
The Unified Modeling Language in practice: the fourteen diagram types, how structure and behaviour split, and how to pick the right diagram for the question you are actually asking.
UML14 min read
- Notation reference02
UML symbols
The symbols UML actually uses, across every diagram type: boxes, ellipses, diamonds, bars and 3D nodes, plus the six relationship lines and the arrowheads that tell them apart.
UML8 min read
- Foundations03
Choosing a diagram
A decision guide to the fourteen UML diagram types: what each answers, which four carry most real work, and which are safe to skip until you meet one.
UML9 min read
- Structure diagrams04
Class diagrams
How to read and draw a UML class diagram: the three compartments, visibility markers, multiplicity, and the difference between association, aggregation, composition, generalization and realization.
UML11 min read
- Structure diagrams05
Class diagram examples
Worked UML class diagram examples: a library with an abstract base class and two subtypes, and a shopping basket with composition, an interface and two realizations.
UML6 min read
- Structure diagrams06
How to draw a class diagram
A step-by-step method for drawing a UML class diagram: which nouns become classes, how to choose a relationship kind, when multiplicities get decided, and when to stop adding detail.
UML7 min read
- Notation reference07
Class diagram symbols
A reference for UML class diagram notation: the six relationship kinds and their arrowheads, the three visibility markers, multiplicity syntax, and what a stereotype in guillemets means.
UML11 min read
- Behaviour diagrams08
Sequence diagrams
How to read and draw a UML sequence diagram: lifelines, activation bars, synchronous and asynchronous messages, replies, and the combined fragments (alt, opt, loop, par) that handle branching.
UML15 min read
- Behaviour diagrams09
Sequence diagram examples
Worked UML sequence diagram examples: a login with an alt fragment, a payment retry with a loop and a self-call, and an asynchronous event publication with no replies at all.
UML6 min read
- Behaviour diagrams10
How to draw a sequence diagram
A step-by-step method for drawing a UML sequence diagram: picking one scenario, choosing participants, ordering messages left to right, adding fragments, and knowing when to split the diagram.
UML7 min read
- Behaviour diagrams11
Use case diagrams
How to read and draw a UML use case diagram: actors, the system boundary, associations, and the include and extend relationships that people most often get backwards.
UML13 min read
- Behaviour diagrams12
Use case examples
Worked UML use case diagrams for a library and an online store, with include, extend and a secondary actor, followed by the same notation used badly and why it fails.
UML8 min read
- Behaviour diagrams13
Activity diagrams
How to read and draw a UML activity diagram: actions, decisions and merges, forks and joins, guards, swimlanes, and the difference between a branch and true parallelism.
UML9 min read
- Behaviour diagrams14
Activity examples
Worked UML activity diagrams: parallel work behind a fork and join, a three-way branch with exhaustive guards, and the difference between a flow final and an activity final in one picture.
UML8 min read
- Behaviour diagrams15
State machine diagrams
How to read and draw a UML state machine diagram: states, transitions with trigger, guard and effect, entry and exit actions, composite states, and history pseudostates.
UML9 min read
- Behaviour diagrams16
State machine examples
Worked UML state machine diagrams: an order lifecycle ending two different ways, a review workflow with a transition back to draft, and triggers versus guards on the way out of a state.
UML8 min read
- Structure diagrams17
Component diagrams
How to read and draw a UML component diagram: components, provided and required interfaces, ball-and-socket notation, ports, and how it differs from a class diagram.
UML13 min read
- Structure diagrams18
Component examples
Five worked UML component diagram examples - a shared catalogue, ports and adapters, a legacy swap, a plugin architecture and a dependency cycle - with what each one is for.
UML9 min read
- Modelling practice19
Drawing a component diagram
A step-by-step walkthrough: choose the parts, draw the boxes, name what each provides, add what each requires, then run the four checks that tell you the diagram is finished.
UML8 min read
- Notation reference20
Component symbols
A reference for every symbol on a UML component diagram: the component box, provided and required interfaces, ball and socket, assembly and delegation connectors, ports and stereotypes.
UML7 min read
- Structure diagrams21
Deployment diagrams
How to read and draw a UML deployment diagram: nodes, devices and execution environments, artifacts, communication paths, and the deploy relationship.
UML7 min read
- Structure diagrams22
Deployment examples
Worked UML deployment diagrams: a classic three-tier stack, a Kubernetes cluster with container images as artifacts, and a horizontally scaled pool behind a load balancer.
UML8 min read
- Structure diagrams23
Object diagrams
How to read and draw a UML object diagram: instance specifications, underlined names, slots with concrete values, links, and how to use one to sanity-check a class diagram.
UML6 min read
- Structure diagrams24
Package diagrams
How to read and draw a UML package diagram: packages, import and access dependencies, merge, nesting, and using the dependency direction to enforce a layered architecture.
UML6 min read
- Structure diagrams25
Composite structure diagrams
How to read and draw a UML composite structure diagram: parts, ports, connectors, delegation, and the difference between this and a class or component diagram.
UML6 min read
- Behaviour diagrams26
Communication diagrams
How to read and draw a UML communication diagram: objects, links, numbered messages, nested decimal sequencing, and when to prefer it over a sequence diagram.
UML6 min read
- Behaviour diagrams27
Sequence vs communication
One interaction drawn as both a sequence diagram and a communication diagram, with what each makes obvious, what each hides, and how to pick between them.
UML7 min read
- Behaviour diagrams28
Timing diagrams
How to read and draw a UML timing diagram: lifelines as value axes, state-change waveforms, duration and time constraints, and when elapsed time matters enough to need one.
UML6 min read
- Behaviour diagrams29
Interaction overview diagrams
How to read and draw a UML interaction overview diagram: interaction occurrences, inline interactions, control flow between them, and how it keeps large sequence diagrams manageable.
UML5 min read
- Structure diagrams30
Profile diagrams
How to read and draw a UML profile diagram: stereotypes, metaclasses, the extension relationship, tagged values, and when extending the language is better than working around it.
UML6 min read
- Modelling practice31
UML with AI
What an AI UML generator is actually good at, the four errors it repeats, how to prompt for a diagram worth keeping, and the two-minute review that catches the rest.
UML9 min read
- Modelling practice32
E-commerce example
A complete worked example of an e-commerce architecture: the domain model, the component view with its service contracts, and the deployment topology, with what each one is for.
UML9 min read
- Modelling practice33
Banking example
A worked banking system example in UML: the double-entry domain model where a balance is derived rather than stored, and the state machine a transfer moves through.
UML8 min read
- Modelling practice34
Microservices example
A worked microservices architecture example: where to put synchronous contracts, where to publish events instead, and how to spot a distributed monolith on paper.
UML8 min read
- Modelling practice35
AWS example
A worked AWS architecture example in UML: the deployment topology with real protocols and ports, and the component view where the vendor names turn back into contracts.
UML8 min read
The ArchiMate series
ArchiMate, from the framework down
The layers, the eleven relationships and the viewpoint mechanism - the enterprise architecture language, taught in the order you need it rather than the order the spec lists it.
- Foundations01
What is ArchiMate
A working introduction to ArchiMate: what the language is for, the layer-and-aspect framework it is organised by, its element and relationship vocabulary, and when to reach for it instead of UML.
ArchiMate10 min read
- Structure diagrams02
Layers and aspects
The ArchiMate framework in detail: business, application, technology, strategy, physical and implementation layers, the active-behaviour-passive aspects, and how the motivation elements cut across all of them.
ArchiMate9 min read
- Notation reference03
Relationships
Every ArchiMate relationship explained: composition, aggregation, assignment, realization, serving, access, influence, triggering, flow, specialization and association - plus the strength order and how derived relationships work.
ArchiMate11 min read
- Modelling practice04
Viewpoints
How ArchiMate separates the model from the views onto it: what a viewpoint is, the standard set and what each is for, how to pick one for a stakeholder, and how to define your own without breaking the model.
ArchiMate8 min read
- Modelling practice05
ArchiMate with AI
How to generate an ArchiMate model from a description: why the layer rules make it more reliable than free-form diagramming, the derived-relationship trap, and what to check.
ArchiMate8 min read
The C4 series
C4, one level of zoom at a time
Context, containers, components and code: four levels of a single model, each answering a question the level above it raised. A convention rather than a notation, which is exactly why it travels.
- Foundations01
What is C4?
The C4 model in one article: what context, container, component and code diagrams each answer, who each level is for, and why C4 defines what to draw rather than how to draw it.
C47 min read
- Structure diagrams02
Container diagram
What counts as a container, how to label the technology and the protocols, and why the container diagram is the level most teams get the most out of and most often skip.
C46 min read
- Modelling practice03
C4 vs UML
Why C4 and UML are not alternatives, what each one actually provides, where they overlap, and how to draw a C4 level in UML notation without breaking either.
C46 min read
The data modelling series
Data models and the diagrams that carry them
Entity-relationship modelling in crow's foot notation, and the trip from a conceptual sketch to a schema a database will actually accept.
- Foundations01
ER diagrams
How to read and draw an entity-relationship diagram: entities, attributes, primary and foreign keys, relationships and cardinality in crow's foot notation, the conceptual-logical-physical progression, and how an ER model differs from a UML class diagram.
Data modelling9 min read
- Notation reference02
Crow's foot notation
The crow's foot cardinality symbols in full: one, many, zero, and the pairs they form; which end of the line each symbol constrains; identifying versus non-identifying relationships; resolving many-to-many; and how crow's foot compares with Chen and with UML multiplicity.
Data modelling8 min read
- Modelling practice03
Schema design
Turning an ER model into a schema a database will accept: choosing keys, normalizing to third normal form with a worked example, when denormalization is justified, implementing inheritance, and generating DDL from the diagram.
Data modelling11 min read
The BPMN series
BPMN, one symbol set at a time
Business Process Model and Notation: events, gateways, pools and the flows between them - the notation business and IT are both supposed to be able to read.
- Foundations01
What is BPMN
A working introduction to BPMN 2.0: the five families of symbol, the difference between sequence flow and message flow, pools and lanes, the three levels of modelling, and when BPMN beats a UML activity diagram.
BPMN10 min read
- Behaviour diagrams02
Events
How BPMN events work: start, intermediate and end by border weight, the message, timer, error, signal and conditional types by interior glyph, throwing versus catching, and boundary events as the way to model exceptions.
BPMN8 min read
- Notation reference03
Gateways
The BPMN gateway types explained: exclusive, parallel, inclusive, event-based and complex, splitting versus merging, default flows, and why an unbalanced inclusive gateway is the classic way to deadlock a process.
BPMN14 min read
- Behaviour diagrams04
BPMN examples
Five worked BPMN 2.0 processes with complete diagrams: a two-pool onboarding collaboration, an expense approval with a rework loop, a support ticket with an escalation deadline, a subscription renewal against a black-box payment provider, and a returns process using an inclusive gateway.
BPMN11 min read
- Modelling practice05
How to draw BPMN
A step-by-step procedure for drawing a BPMN 2.0 diagram: choosing the start and end events first, listing steps as verb phrases, drawing the happy path in one pool, adding gateways and loops, deciding whether a second pool is warranted, and the five checks that catch most defects.
BPMN9 min read
- Notation reference06
BPMN symbols
A reference for every BPMN 2.0 symbol: tasks and their type markers, subprocesses and call activities, the three event borders and their glyphs, the five gateway types, sequence against message flow, default and conditional flows, pools, lanes, data objects and artifacts.
BPMN9 min read
- Modelling practice07
BPMN vs activity diagram
The two notations draw the same process and diverge in four places: who reads them on sight, what a swimlane boundary is allowed to mean, how an interruption is drawn, and whether the file can be handed to an engine that runs it.
BPMN8 min read
The interop series
Getting a model out, and back in
XMI, Sparx .qea and Mermaid - what each format carries, what it silently drops, and how to move a model between tools without discovering the losses later.
- Modelling practice01
UML to XMI
What XMI 2.5.1 actually carries between UML tools: the model transfers reliably, the diagram layout usually does not, and the reason is a decade of optional diagram interchange.
Exports6 min read
- Modelling practice02
Sparx .qea round trip
A .qea file is a SQLite database with Enterprise Architect's repository schema inside it. What that means for a round trip, which tables carry the model, and what a receiving tool cannot reconstruct.
Exports6 min read
- Modelling practice03
UML to Mermaid
What survives when a UML model becomes Mermaid, which diagram kinds Mermaid actually supports, and why a lossy text format is still the right answer for documentation that has to stay current.
Exports5 min read
The practice series
The part no specification covers
How much to model, what to call things, and how to keep a model alive after the project that created it - the decisions that decide whether anybody reads it in a year.
- Modelling practice01
Which language to use
UML, ArchiMate, BPMN and C4 get compared as if they were substitutes. They are not: each answers a different question about a different scope, and the three places they truly overlap are the only places where a choice is being made at all.
Practice9 min read
- Modelling practice02
Scoping a model
A test for deciding how much of a system to model: name the decision each view informs, and delete the views that inform none. Plus the three failure modes of an unscoped model.
Practice6 min read
- Modelling practice03
Naming conventions
Naming conventions for UML and ArchiMate models argued from searchability: nouns for classifiers, verbs for behaviour, the domain's own words, and what to do about acronyms.
Practice5 min read
- Modelling practice04
Keeping a model current
Why architecture models go stale and what actually prevents it: attaching the model to a step that already happens, shrinking it to what the team will maintain, and deleting the rest.
Practice6 min read
The product
About Archyno
What the tool does, what it exports, and how a team works in it together - written plainly, including the parts that are not built yet.
- Modelling practice01
Why Archyno
What Archyno is, what it exports, how a team works in it, and where it stops: UML 2.5.1 and ArchiMate 4 in the browser, a shared model, notation-aware AI, and a .qea file the rest of the business can open.
Archyno10 min read
Where to next
Six tracks, each read in order rather than picked from.
Editable starting diagrams, already legal, in four notations.
Whole systems modelled end to end, with the reasoning shown.
Draw something now and export it - no account, fifteen seconds.