If you've worked on backend code for a while, you've probably met a function like this. It started small, it works, and nobody wants to touch it.
async function handleLabOrder(order) { const labRef = await labApi.submit(order); const results = await pollUntilReady(labRef); await ehr.updateRecord(order.patientId, results); if (results.abnormal) { await notifyDoctor(order.doctorId, results); } await billing.createInvoice(order); } This one handles a hospital lab order. It sends the test to the lab, waits for the results, saves them to the patient's record, alerts the doctor if something looks wrong, and creates the bill. That's five steps across four outside systems, written as ten lines that read neatly from top to bottom.
On a good day it does exactly what it says. The trouble is that these steps don't run in seconds. The lab might take an hour. The doctor might not look until the next morning. Any of the four systems can be down at the moment you call it. A function expects to run from start to finish in one go, and this process doesn't work that way.
So this isn't really a function. It's a long-running workflow squeezed into the shape of one, and that mismatch causes most of the trouble that comes later.
Questions this code can't answer
Ask it a few ordinary questions and the gaps show up quickly.
What happens if the process restarts while pollUntilReady is running? The lab already has the order, but your process has forgotten it. Either the order is lost, or the retry submits it a second time.
Where does the code wait while the doctor reviews abnormal results? It doesn't. notifyDoctor sends a message and moves straight on to billing. The review only exists in someone's head.
A nurse asks where order #4821 is right now. To answer, someone has to search logs across four services and hope the IDs match up.
Billing switches vendors next quarter. That means changing this function, plus every other function that copied the same invoice call.
None of these are rare edge cases. They're normal days for any process that touches several systems and involves people.
How it usually gets patched
Teams tend to fix these one incident at a time. A retry wrapper goes around the lab call. A status column appears on the orders table. A cron job checks for orders stuck longer than an hour, and a Slack alert fires when it finds one.
Each fix makes sense on its own. Add them up, though, and the real workflow ends up spread across a function, a database column, a cron job, and a chat channel. Drawing the full process on a whiteboard now means opening three repos first.
At that point it helps to call the code what it is: a sequence of steps with state, waiting, failures, and people in the middle. That kind of thing works better when it's treated as a workflow on purpose.
The same logic as a workflow
Here's the same process written as a workflow definition. It's illustrative pseudo-config, not the syntax of any particular tool.
workflow: lab_order steps: - name: submit_to_lab call: lab.submit retry: { max_attempts: 5, backoff: exponential } - name: wait_for_results wait_for_event: lab.results_ready timeout: 24h - name: update_record call: ehr.update_record - name: doctor_review when: results.abnormal human_task: assign_to: order.doctor_id timeout: 8h on_timeout: escalate_to_on_call - name: create_invoice call: billing.create_invoice The business logic hasn't changed. What changes is who handles everything around it.
Progress is saved after each step, outside your process. If something crashes during wait_for_results, the run picks up there instead of sending the order to the lab again.
Waiting becomes a normal step. Waiting a day for the lab or eight hours for a doctor is written into the flow, with a timeout, instead of living in a polling loop someone has to maintain.
The doctor's review gets an owner, a deadline, and an escalation path. It stops being a notification that nobody follows up on.
Finding order #4821 becomes a lookup, because the engine knows which step every run is on.
Changing billing vendors means editing one step. Adding something new, such as an AI step that summarizes abnormal results for the doctor, means adding one more step rather than rewriting the function.
When it isn't worth it
Plenty of code should stay a plain function. If the steps finish in milliseconds, the calls are safe to repeat, nobody waits on a person, and a failure can just be retried from the top, a workflow engine is extra infrastructure you don't need. A two-step script that runs once a night doesn't need a flowchart.
A rough test: if you've already added a status column, a cron job that hunts for stuck items, or an admin button that says "retry from step 3," you've built half a workflow engine by hand. The remaining question is whether you want to keep maintaining it yourself.
Code or config?
Once teams decide to treat a process as a workflow, they usually split into two camps.
One camp writes workflows as code. Steps are ordinary functions, and the engine handles saving progress and retries behind the scenes. You keep your usual language, type checking, and tests.
The other camp writes workflows as data, like the YAML above. You get a diagram that people outside engineering can read, changes that don't always need a deploy, and a clear picture of where each run stands. The risk is that a large definition can turn into a config file nobody wants to open.
Both approaches have tradeoffs, and teams land differently depending on who needs to read and change the flow.
So which one does your team use, and what pushed you that way? If you've seen a workflow-as-data setup grow into an unreadable YAML file, I'd like to hear how you got out of it.