UML diagrams
Every diagram on this site so far has been one flavor of UML - the class diagram - because it is the one design patterns actually run on. UML has several other diagram types, and four of them turn up constantly in interviews and design docs: use case, sequence, activity and state machine. All five model the same login flow below, each answering a different question about it.
Class diagram
What are the pieces, and how are they wired together? Boxes for classes and interfaces, split into name / fields / methods; arrows for extends, implements, and the four relationships in Class relationships. This is the notation every diagram elsewhere on this site is drawn in - see Objects, classes & interfaces for the full anatomy of one box.
When to reach for it: any time you are about to write code with more than one class in it - it is the default, load-bearing diagram of the bunch. When not to bother: for a single class with no interesting relationships, just write the class; a box with one name in it is not a diagram.
Use case diagram
What can the actor do, from outside the system, without touching a single internal detail? The lightest UML diagram on purpose: a stick-figure actor, a system boundary box, and one oval per goal the actor can accomplish. No classes, no messages, no code - just capability.
Use case diagram: one actor, three goals, zero internal detail.
Use this in the first ten minutes of a design interview, before you have decided on a single class name - it is a checklist of "what does this system need to let someone do", which is the actual scope of the problem.
When to reach for it: scoping, or when a system has more than one kind of actor (a user and an admin, say) and you need to nail down who can do what before anyone argues about implementation. When not to bother: once the actors and goals are obvious and agreed on - three ovals restating "users can log in and log out" a week into the project is decoration, not information.
Sequence diagram
In what order do these participants talk to each other, for one specific scenario? Each participant gets a vertical lifeline; time runs top to bottom; a horizontal arrow is one message; the thin vertical bar on a lifeline is an activation - that participant is currently doing work.
Sequence diagram: solid arrows are calls, dashed arrows are returns. Read top to bottom.
The class diagram above told you LoginForm can call AuthService. The sequence
diagram tells you it does, in this exact order, for this exact scenario - the two
diagrams answer different questions about the same three classes.
When to reach for it: one specific interaction where the order or timing of messages is the point - a cache miss that has to fall through to a slower store, a retry, a callback that arrives out of order. When not to bother: a single method calling a single getter. If the arrows would just restate the call stack with no interesting ordering or branching, skip the lifelines and say it in a sentence.
Timing is exactly where a sequence diagram earns its keep over just reading the code - a cache lookup that misses and has to fall through to the database has an ordering that is easy to get backwards in your head but obvious once it is drawn:
Sequence diagram: a cache miss falling through to the database, then backfilling the cache. The next get(key) skips the database entirely.
Nothing about that ordering is visible in a class diagram of Client, Cache and
Database - Cache and Database look identical from the outside. The sequence
diagram is the only one of the five that captures "this call happens, and only then does
that one."
Activity diagram
What happens, step by step, including every branch? A flowchart: rounded start/end nodes, rectangles for actions, a diamond for a decision. No participants, no lifelines - just the process.
Activity diagram: a filled circle starts it, a ringed circle ends it, a diamond branches it.
When to reach for it: a business process or workflow with real branching - an
approval chain, an order pipeline with a refund path, anything with more than one
decision diamond worth drawing. When not to bother: a single method's control flow.
if (x) return a; else return b; is not worth a flowchart - that is what the code itself
is for.
State machine diagram
What stable configurations can this object be in, and what triggers moves between them? Rounded boxes are states, arrows are transitions labeled with the event that causes them. Unlike the activity diagram, there is no implied "and then it's done" - a state machine can sit in one state indefinitely until an event arrives.
State machine diagram: filled dot is the initial state, arrows are labeled with the triggering event.
This is the diagram the State pattern implements directly - one class per bubble,
one transition() per arrow. If you catch yourself drawing a state machine for a class,
that class is a strong State-pattern candidate.
When to reach for it: the moment an object's legal transitions matter more than any single path through them - an order, a traffic light, a TCP connection. When not to bother: an object with no real states, or one where every transition is legal from everywhere - a state machine with one bubble and an arrow back to itself is not modelling anything.
The OrderStatus enum from Objects, classes & interfaces
is a state machine that was hiding in plain sight - five named values, but only some of
the moves between them are actually legal. PENDING walks forward to CONFIRMED,
SHIPPED and DELIVERED in order, but it can also jump straight to CANCELLED - and once
an order is CANCELLED or DELIVERED, nothing moves it anywhere:
State machine diagram: the same five OrderStatus values, now with the legal moves between them drawn in - not every value can reach every other value.
The enum told you the five values that exist. The state machine tells you the rule the
enum alone could never enforce: you cannot go from SHIPPED back to PENDING, and once
you hit DELIVERED or CANCELLED, that object is done changing.
Which one do you actually reach for
- Scoping a system before writing any code: use case.
- Explaining one specific bug or one specific call flow: sequence.
- Documenting an algorithm or a business process with branches: activity.
- Modelling an object whose legal next moves depend on where it currently is: state machine.
- Everything about the static shape of the code itself: class diagram, which is why it is the one used everywhere else on this site.
Check yourself
You need to show a login attempt as a series of messages passed between User, LoginForm, AuthService and Database over time. Which diagram fits?