Notes
The problem
Here is the problem. The hiring process is described in one sentence: screen the CV, then run a background check, then the tech interview, then send the offer. So the first version of the code does exactly that, one after another. The background check takes three days and the interview two, so every decision takes five days. Worse, nobody wrote down what happens when the CV fails, or when only one of the checks fails.
- "we screen the CV, then do a
- background check, then the
- tech interview, then offer"
- questions left open:
- must the interview wait for
- the background check?
- what if the CV fails?
- what if one check fails?
- who does each step?
The idea
The idea in one sentence: an activity diagram shows the steps of a process, the choices in it, and which steps can run at the same time. It looks like a flowchart with extra powers. A filled circle is the start, and a circle with a ring around it is the end. Rounded boxes are actions. Arrows show the flow from one action to the next. Diamonds are choices, thick bars split and join parallel work, and swimlanes show who does each step.
- start: filled circle
- end: circle with a ring
- action: rounded box
- arrow: control flow
- decision / merge: diamond
- fork / join: thick bar
- swimlane: a column per actor
- object node: a plain box
- one diagram = one process
Start and actions
Every activity has one start node, a small filled circle. From it, an arrow leads to the first action. An action is one step of work, drawn as a box with rounded corners, and named with a verb, like submit application or screen CV. The arrows between actions are called control flow: when one action finishes, the next one can begin. Keep each action at the same level of detail, not one huge step next to a tiny one.
Decisions and guards
A decision is a diamond with one arrow in and two or more arrows out. Each outgoing arrow carries a guard, a condition in square brackets. After screening, if the candidate meets the basics, we go on. Else, we send a rejection. Guards must cover every case, and two guards should never be true at the same time. Writing else as the last guard is a simple way to make sure nothing falls through.
- [meets basics] go on
- [else] reject
- rules:
- every case is covered
- no two guards true at once
- [else] is a safe last guard
- a decision is a diamond,
- not an action
Merge and end
Paths that split at a decision often meet again later. A merge is the same diamond shape, but with several arrows in and one arrow out. Whether we sent an offer or a rejection, the flow continues to the same end. A merge does not wait for anything, because only one of its incoming paths is ever taken. After it comes the final node, a filled circle inside a ring. When the flow reaches it, the whole activity is finished.
Fork
Now the fix for our five day problem. The background check does not need the interview, and the interview does not need the background check. So we put a fork after the first decision. A fork is a thick black bar with one arrow in and several arrows out. Unlike a decision, every outgoing flow starts, all at the same time. The vendor begins the background check while the hiring team runs the interview.
Join
A join is the matching thick bar with several arrows in and one arrow out. It waits until every incoming flow has arrived, and only then lets the flow continue. If the interview is done on day two, it waits for the background check to finish on day three. Now the decision takes three days, the longest branch, instead of five, the sum of both. After the join, a second decision asks: did everything pass?
Merge vs join
These two pairs look similar, so compare them. A decision and a merge use diamonds. Only one path runs, and the merge does not wait. A fork and a join use thick bars. All paths run, and the join waits for every one. Mixing them is a real bug. If you put a join after a decision, it waits forever for the path that was never taken. In code, that is a thread waiting for a result that will never come.
- decision then merge (diamond)
- only ONE path runs
- merge does not wait
- fork then join (thick bar)
- ALL paths run
- join waits for every one
- join after a decision:
- waits forever for a path
- that never ran
The whole diagram
Here is the whole workflow. Start, submit the application, screen the CV. If the basics are missing, reject. Otherwise fork into the background check and the tech interview, and join when both are done. If both passed, send the offer, else send a rejection. Both paths merge and reach the end. Every case now has an ending, including the two we forgot in the first version, and the slow part runs in parallel.
Swimlanes
Swimlanes split the diagram into columns, one per actor or department. Every action sits in the lane of whoever does it. The candidate submits. The recruiter screens, and later sends the offer or the rejection. An outside vendor runs the background check, and the hiring team runs the interview. Each arrow that crosses a lane is a hand-off between people or systems, and hand-offs are where delays and lost messages usually hide.
- | Candidate | Recruiter |
- | submit | screen |
- | | offer or |
- | | reject |
- | Vendor | Hiring team |
- | bg check | interview |
- an arrow crossing a lane
- is a hand-off
Object flow
Sometimes it helps to show the data that moves between actions. This is called object flow. Submit application produces an application object, drawn as a plain rectangle on the arrow, and screen CV consumes it. Each check produces a check result, and send offer produces an offer letter. You can write a state in brackets, like application, screened. Use object flow lightly, only where the data is important, or the diagram gets crowded.
- [Submit] --> Application
- --> [Screen CV]
- [Background check]
- --> Check result
- [Send offer]
- --> Offer letter
- an object box can show its
- state: Application [screened]
Diagram to code
The diagram turns into code almost line by line. Each action is a method call: submit, screen, offer, reject. Each decision is an if, and its guards are the condition and the else. The fork and join live in one helper that returns both check results. Both paths go through the same finish method, which is the merge, and then the method returns, which is the final node. The shape of the code matches the shape of the diagram.
String run(Application app) {
submit(app); // action
if (!screen(app)) { // decision
return finish(reject(app));
}
List<CheckResult> r = forkAndJoin(app);
boolean ok = r.stream()
.allMatch(CheckResult::passed);
return finish(ok ? offer(app)
: reject(app));
} Fork and join in Java
Here is the fork and join in Java. Each branch starts with CompletableFuture supply async on a thread pool, so both checks run at the same time. That is the fork. Then allOf followed by join blocks until every branch has finished. That is the join bar. Finally we read the two results in a fixed order, background check first, so the output is the same on every run, no matter which branch finished first.
// fork: both flows start now
var bg = CompletableFuture.supplyAsync(
() -> backgroundCheck(app), pool);
var iv = CompletableFuture.supplyAsync(
() -> techInterview(app), pool);
// join bar: wait for every flow
CompletableFuture.allOf(bg, iv).join();
// read results in a fixed order
return List.of(bg.join(), iv.join()); Run it
The demo runs two paths. Application J forty one has five years of experience, so it passes screening and forks. The background check comes back clear after three days, and the interview scores eight out of ten after two. The join waits for both, everything passed, and an offer goes out after three days, not five. Application J forty two also passes screening, but scores four in the interview, so after the join it gets a rejection.
Which diagram when
When should you pick an activity diagram? Use it for a process with several steps, choices and parallel work, often across several people or systems, like hiring, order fulfilment or a loan approval. Use a sequence diagram when the question is which object calls which, in what order. Use a state diagram when one object moves through states, like an application going from submitted to screened to hired. They answer different questions.
- activity diagram:
- steps of a whole process,
- choices, parallel work
- sequence diagram:
- messages between objects
- in one scenario
- state diagram:
- the states of ONE object
- and what moves it
- one fact, one diagram
Interviews and mistakes
In interviews, an activity diagram helps most in workflow heavy problems: an order checkout, an approval chain, a vending machine purchase, or an ATM withdrawal. Watch for the classic mistakes. A join after a decision waits forever. Guards that overlap or miss a case. A process with no path for failure. Actions named after classes instead of verbs. And branches drawn in parallel that really depend on each other's results.
- a join after a decision
- (waits forever)
- guards that overlap or miss
- a case
- a decision with no way out
- for failure
- class names as actions
- every tiny step drawn
- parallel branches that
- secretly depend on each other