6. The mental model: workflow as code

Description

By the end of this lesson you will have a single mental model that organizes everything you've seen so far: workflow as code. You'll be able to answer the question that sounds philosophical and is completely practical —which workflow is "the real one," the one in the editor or the one in the repository?— you'll know the complete work cycle (edit → export → commit → review → promote), and you'll understand why thinking of the n8n instance as a runtime and the repository as the source solves versioning, environments, and testing all at once.

This matters because up to this point you've accumulated five problems —what versioning is, why the market asks for it, why export/import isn't enough, what's inside the JSON, what breaks when you move it— and you're still missing the frame that ties them together. A mental model isn't decoration: it's what lets you make a new decision, one that isn't in any lesson, and know what to do. When on a real project you ask yourself "where should this configuration live?" or "what exactly am I promoting to production?", the answer will come from this model, not from memorizing loose rules.

Connection to the module: this is the lesson that turns five pieces into one system. Lessons 3, 4, and 5 were the diagnosis of the problem; this is the reformulation that solves it. And it's the bridge to the rest of the guide: the cycle presented here is, literally, the skeleton of Modules 2 through 6. "Export" and "commit" are Modules 2 and 3; "review" and "promote" are Modules 5 and 6; the environments where each version runs are Module 4. Lesson 7 puts a price tag on each part of this model (what's free, what costs money), and lesson 8's project has you take the cycle's first step with order-triage.

The recipe book and the kitchen

Let me offer you an image we'll use for the rest of the guide, because it resolves almost every confusion in one shot.

Think of a restaurant chain with several branches. At a central office there's a master recipe book: a book where every recipe is written down precisely —quantities, steps, times, the reasoning behind each decision. That recipe book is the chain's truth. It's what defines what each dish is.

At every branch there's a kitchen running: cooks, pans, the dish coming out hot. The kitchen is where the food happens. But the kitchen doesn't invent the dishes: it cooks them following the recipe book. If a cook improvises and changes a dish without updating the recipe book, the chain has a problem —that branch now does something different from the others, and nobody knows why.

Now the key question: if a kitchen burns down, is the dish lost? No. A kitchen was lost. You open another one, hand it the recipe book, and within a week that branch makes exactly the same dishes. What the chain cannot afford to lose is the recipe book. The kitchen is replaceable; the recipe book is not.

Translate that to n8n:

• The master recipe book is your repository: your workflows' JSON, versioned, with the history of every change and its reason. It's the truth. It defines what each workflow is.
• The kitchen is your n8n instance: where workflows run, process real orders, get executed. It's where the automation happens.
• The fire is your instance getting corrupted, deleted, or needing to be migrated. If you have the recipe book —the repository— you haven't lost your workflows: you spin up a new instance, load the JSON, and you're back.

This is the complete reformulation of what you studied. In lesson 1 I said, without fully explaining it, that "the repository, not the instance, is the source of truth." Now you know why: because the instance is the kitchen —replaceable, where things happen— and the repository is the recipe book —the truth, what can't be lost. That's the "workflow as code" mental model, and everything else follows from it.

The identity question: which workflow is "the real one"?

It sounds like a dinner-table question and it's the most practical decision in the whole guide. You have your order-triage workflow open in the n8n editor, and you have its JSON in the cumbre-automations repository. Which of the two is "the workflow"?

Before this module, the intuitive answer was "the one in the editor, obviously; the one in the repo is a copy." After this module, the correct answer is the opposite: the one in the repository is the workflow; the one in the editor is one instance of it running.

This inversion is the moment someone moves from builder to system owner, so it's worth pausing on. Why is the repo "the workflow" and not the editor?

Because the editor is ephemeral and the repo is permanent. What's in the editor lives in that instance's database. If the instance dies, it dies with it. The repo outlives any instance.

Because the editor has no history and the repo does. The editor shows you the state right now. The repo has every state, with its date and its reason. A workflow's identity isn't just how it is today; it's also how it got there, and that only exists in the repo.

Because there can be many editors and only one repo. This is the point that seals it. Once you have environments —dev, staging, prod— you're going to have the "same" order-triage running on three different instances at once. Which of the three is "the workflow"? None: they're three kitchens cooking the same recipe. The workflow —the recipe— is one, and it lives in the repo. The instances are executions of it.

When you adopt this inversion, a lot of decisions solve themselves. "Where do I make the change?" —in the repo, and from there it flows down to the instances, not the other way around. "What do I review before approving?" —the change in the repo, with a diff. "What do I promote to production?" —a version from the repo, not an editor. The instance stops being the center of the universe and becomes what it actually is: a place where the workflow runs, one of several possible ones.

Source and runtime: two words that organize everything

There are two terms software engineering has used for decades that, applied to n8n, click into place with everything above. It's worth adopting them because they're precise.

The source is the description of what a system should do, written down permanently and in a versionable way. In a classic program, the source is the source code the programmer writes. In n8n, the source is your workflows' JSON in the repository. It's the recipe book.

The runtime is where the system actually runs. In a classic program, the runtime is the program executing on a computer. In n8n, the runtime is your instance processing orders. It's the kitchen.

The relationship between the two has a direction, and that direction is the key: the source governs the runtime, not the other way around. You write in the source, and the source gets deployed to the runtime. The runtime is a consequence of the source. When someone changes something directly in the runtime —edits a workflow in production without going through the repo— they flip the arrow, and that's where problems start: the runtime now says something the source doesn't know about, and the next time you deploy from the source you're going to overwrite that change without ever finding out.

This has a name in n8n and is a real temptation: editing in the production editor "just this once, because it's urgent." The source/runtime model tells you why it's dangerous: you just created a difference between the recipe book and the kitchen, and that difference is invisible until it bites you. A system owner's discipline is that the change is always born in the source. If it's urgent, it gets done fast in the source and deployed fast, but it gets done in the source.

Here's an honesty I owe to n8n's reality: the tool lets you edit in the runtime. There's no wall stopping you in Community. The source/runtime model is a discipline you adopt, not a barrier the tool enforces —except in the paid features, which do put up barriers, a topic for lesson 7. That's exactly why it's a mental model: its value is in how it changes your decisions, not in forcing you.

The work cycle: edit, export, commit, review, promote

The source/runtime model becomes action through a five-step cycle. This cycle is the heartbeat of everything that follows in the guide, so get to know it even if you don't yet know how to execute each step.

   ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
   │   EDIT   │ ──► │  EXPORT  │ ──► │  COMMIT  │ ──► │  REVIEW  │ ──► │ PROMOTE  │
   │ (in dev) │     │(to JSON) │     │(to repo) │     │(the diff)│     │(to prod) │
   └──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘
        ▲                                                                    │
        └────────────────────────────────────────────────────────────────────┘
                          (the next change starts over)

Let's go step by step, with order-triage:

1. Edit. You make the change in your dev instance's editor —never in prod. Here you build, with test credentials and synthetic data, with no fear, because nothing you touch affects the real thing. This is the only step that resembles what the builder used to do; the difference is where you do it (in dev, not production) and that it doesn't end here.

2. Export. You pull the workflow out as JSON —the Download from lesson 3. You turn the editor's "building" into the text "blueprint." This is the moment the change leaves the runtime and gets ready to enter the source.

3. Commit. You save that JSON in the repository with a note explaining the change —"send orders over 5000 to manual review." A commit is an entry in the repo's history: the moment your change becomes part of the recipe book, with date, author, and reason. That's Module 2. Here the change stops being ephemeral and becomes permanent and versioned.

4. Review. Before that change reaches production, someone —a coworker, or you with fresh eyes, or even an AI-assisted review— reads it as a diff: sees exactly what changed and decides if it's good. This is the "review" capability from lesson 3, now possible because the change is versioned. That's Module 6.

5. Promote. The reviewed, approved change gets deployed: it goes down from the source to the runtimes, moving through environments —from dev to staging to prod. Promoting isn't "rebuild it in production"; it's taking the exact version you tested and approved, and loading it into the next environment. That's Module 6.

And then, the cycle repeats: the next change starts again at "edit," on top of what's already in the source.

Notice what this cycle guarantees, almost without you noticing:

• You never edit production directly (you start in dev).
• Every change gets versioned (step 3) before it reaches anywhere important.
• Every change gets reviewed (step 4) before production.
• What reaches production is exactly what you tested (step 5 promotes a concrete version, not a rebuild).

Those four guarantees are precisely what separated the system owner from the builder in lesson 2. They aren't four rules you memorize; they're automatic consequences of following the cycle. That's the power of a good mental model: discipline stops being an act of willpower and becomes "the natural way of doing things."

Worked example: an order-triage change through the cycle

Let's follow a real change from start to finish, so the cycle stops being a diagram and becomes a story. Cumbre wants orders over 5000 pesos to go to manual review.

Edit (in dev). You open order-triage on your dev instance. You adjust the decision node for the new threshold. Since you're in dev, you run the workflow ten times with synthetic test orders —one for 6000, one for 4000, one for exactly 5000— to see the rule behaves as expected. The CRM it touches is the test one; the AI agent uses the dev credential. None of this affects the real Cumbre. What to expect: you see on the panel that the 6000 one goes to review, the others don't. Good.

Export. You do Download. Now you have order-triage.json with the change.

Commit. You save that file in cumbre-automations with the note route orders over 5000 to manual review. The repo records: who (you), when (today), what (the diff, two lines), why (the note). The change is now part of the recipe book. What to expect: if someone looks at the repo's history a year from now, they'll be able to read exactly this decision and its reason.

Review. Your coworker opens the diff. She sees two changed lines —the threshold from one value to another, inside parameters, a stable field (lesson 4). There's no position noise or ID noise because the repo is normalized (Module 3). In ten seconds she understands the change, sees it's correct, and approves it. What to expect: a review that takes seconds, not archaeology, thanks to the change being versioned and the diff being clean.

Promote. The approved change gets deployed to staging, where it's tested once more under conditions close to production, and from there to prod. What reaches prod is exactly the JSON you tested in dev and reviewed in the diff —not a rebuild, not "I do it again in production and hope it comes out the same." What to expect: zero surprises in production, because production receives what you already saw work.

And if, against all odds, something goes wrong in prod, you have the step the cycle makes possible: you go back to the repo's previous version —which is still there, with its date— and promote it again. Rollback in a minute. That's what the candidate from lesson 2 answered in their good interview, and now you see it wasn't a trick: it was this cycle.

What this model does NOT mean

Because the name is "workflow as code," it's worth clearing up three misunderstandings that scare people coming from the visual world, because none of the three is true.

It does not mean you're going to write JSON by hand. You keep building your workflows in n8n's visual editor, dragging and connecting nodes, exactly as always. The JSON is what comes out of the editor when you export, not something you type. Across the whole cycle, the "edit" step is visual; the JSON only appears at "export," and from there on it's handled by the version system, not your fingers. "Workflow as code" doesn't turn you into a JSON programmer; it gives you the benefits programmers have over their code —history, review, rollback— without you ever leaving the canvas.

It does not mean the visual editor is bad or for beginners. The editor is the best tool for building, and you keep using it. What the model adds isn't a replacement for the editor, it's a layer around it: the editor builds, the repo versions, the environments run. Each one does what it does well. Nobody's asking you to abandon the visual world; they're asking you not to leave it loose without a version.

It does not mean you need to know how to program. The model requires that you understand the cycle and the direction of the arrow, not that you know JavaScript or software engineering. Git —the tool for the "commit" step— is taught from zero in Module 2, for someone who's never touched it. The mental model is conceptual; its value is in how you decide, and deciding well doesn't require programming. An automator who's never written a line of code can be a flawless system owner if they adopt this frame.

Put differently: "code" here isn't the language you work in; it's the discipline with which you treat your work. You treat the workflow with the same care a good team treats its code —versioned, reviewed, deployed across environments— even though your workflow is a hundred percent visual.

Why this frame solves three problems at once

The most elegant thing about the "workflow as code" model is that it doesn't solve one problem: it solves three, and it solves them with the same idea. It's worth spelling this out explicitly, because it's why this is the guide's foundational module.

It solves versioning. If the source is the repo and every change goes through a commit, then by construction you have history, review, and rollback —the three capabilities that were missing in lesson 3. You don't add them separately; they come bundled with treating the repo as the source of truth.

It solves environments. If the workflow is the recipe and the instances are kitchens, then dev/staging/prod are simply three kitchens cooking the same recipe with different ingredients —test credentials in dev, real ones in prod. The same recipe, different ingredients per kitchen: that's exactly what solves lesson 5's per-instance credentials problem. Environments stop being a separate topic and become a natural consequence of separating source from runtime.

It solves testing. If you can deploy the exact same version to dev as to prod, then you can test in dev with the certainty that what you're testing is identical to what's going to run in prod. Testing stops being "I hope production behaves the same" and becomes "it's the same JSON, it has to behave the same." Module 5's sandbox rests entirely on this guarantee.

The three problems —versioning, environments, testing— looked like three separate topics, and they're three faces of a single idea: separate what the workflow IS (the source, the recipe) from where it RUNS (the runtime, the kitchen). Once you make that separation, all three sort themselves out. That's why it's worth installing the mental model now, in module 1, before the technique: because every module that follows isn't a new topic, it's a piece of this same model made operational.

Common mistakes

Treating the instance as the source of truth and the repo as a backup (conceptual). What happens: someone sets up a repository but keeps making changes in the editor and "exporting to the repo every now and then" as a backup. The arrow is inverted: the truth still lives in the instance, and the repo lags behind, incomplete. Sooner or later the repo and the instance diverge and the repo stops being useful. Why it happens: it's the builder's habit —the editor was always the center— and it's hard to flip. How to spot it: if your flow is "change in the editor, then back it up to the repo," you have the arrow backward. How to fix it: adopt the habit that the change is born thinking about the source. In practice you keep editing in the dev editor (step 1 of the cycle), but the change isn't "done" until it's in the repo (step 3), and production only receives what comes out of the repo (step 5). The repo isn't where you back up; it's where you deploy from.

Editing directly in production "just this once" (practical and dangerous). What happens: there's an emergency, someone goes into the prod editor and makes the change right there, without going through dev or the repo. It works in the moment, and it creates a silent difference between the runtime and the source. The next time someone deploys from the repo, they overwrite that urgent change without knowing it existed, and the "fixed" problem reappears. Why it happens: urgency makes the cycle feel like bureaucracy. How to spot it: if your production instance has changes the repo doesn't know about, they've already diverged. How to fix it: even in an emergency, the change is born in the source —it gets done fast in dev, committed, promoted fast. If you truly did touch production by hand for an extreme emergency, the mandatory next step is to reflect that change in the repo immediately, so the recipe book matches the kitchen again.

Confusing "promote" with "rebuild" (conceptual). What happens: someone understands they have to get the change to production and interprets that as "I redo the same change in the production editor." Now there are two separate builds that should be the same but were made independently, and any difference between them is a bug waiting to happen. Why it happens: without the source/runtime model, "get it to production" sounds like "redo it over there." How to spot it: if your way of deploying is repeating the steps on another instance, you're rebuilding, not promoting. How to fix it: promoting is moving the same artifact —the same JSON you tested— to the next environment, not remaking it. What guarantees production behaves like the test is that it's, byte for byte, the same thing. Module 6 gives you the concrete ways to promote without rebuilding.

Believing the mental model is optional because "I work alone" (conceptual). What happens: someone who automates solo concludes that source/runtime, repos, and cycles are things for large teams, and that it's overkill for one person. Why it happens: the word "collaboration" dominates the conversation about versioning, and someone working alone doesn't feel addressed by it. How to spot it: if your justification for skipping the model is "I have no one to collaborate with," check it. How to fix it: remember that of the four capabilities from lesson 3, only one (collaboration) requires a team; the other three —history, review, rollback— serve you just as well solo. "You, three months from now" is, for all practical purposes, a different person: they won't remember why you changed the threshold, and they'll appreciate the recipe book as much as a coworker would. The mental model is for anyone who wants their system to outlive their own memory.

Exercises

Exercise 1 — Answer the identity question. A colleague tells you: "the repo is just a backup copy; the real workflow is the one running in production." Write your reply in four or five sentences, using the recipe-book-and-kitchen image, and explaining why the arrow goes from source to runtime and not the other way around.

See solution

One possible reply:

"I see it the other way around: what's running in production is an execution of the workflow, not the workflow. Think of a restaurant chain: the production kitchen is one branch cooking; the recipe book at the central office is what defines what each dish is. If the kitchen burns down, you haven't lost the dishes, you lost a kitchen —you open another and hand it the recipe book. Same here: if the production instance gets corrupted, with the repo you spin up another one and load the JSON. That's why the change has to be born in the repo and flow down to production, not the other way around: if someone improvises in the kitchen without updating the recipe book, that branch does something nobody else knows about, and the next deployment overwrites it. The repo is the truth; the instance is one of several kitchens."

Why it works: if your reply separated "the workflow" (the recipe, permanent) from "an execution of the workflow" (the kitchen, replaceable) and explained the direction of the arrow, you already have the complete mental model. Notice the best answer doesn't deny that production matters —it matters a lot, it's where the business happens— but it does deny that production is the source. That distinction is everything.

Exercise 2 — Place each module in the cycle. The cycle has five steps: edit, export, commit, review, promote. For each one, say which module of this guide teaches it in depth (you can check the DESIGN's syllabus or lesson 1's). Then identify which step of the cycle does NOT appear explicitly in the list of five but is where Module 5 lives.

See solution

• Edit — this is the skill you bring from the building guides; this guide places it in the right environment (dev), which is Module 4.
• Export — Module 3 (exporting with the CLI, normalizing, structuring the repo). The editor's Download you saw in this module's lesson 3.
• Commit — Module 2 (Git from zero: staging, commits, branches, rollback).
• Review — Module 6 (reviewing changes as diffs, including reviewing AI changes).
• Promote — Module 6 (promoting across environments, rollback, runbook).

The step that isn't explicit in the five but is central: testing. It lives hidden inside "edit" (testing in dev) and between "review" and "promote" (testing in staging before prod). It's all of Module 5, sandbox testing. The five-step cycle is the skeleton; testing is what gives the promotion its confidence.

Why it works: this exercise shows you the whole guide is this cycle unfolded. It isn't six separate topics; it's the five phases of a single flow, plus the testing that makes it trustworthy. If you have the cycle in your head, you have the map of everything left to learn.

Exercise 3 — Diagnose a flipped arrow. Read this description of how a team works and point out exactly where they flip the source→runtime arrow, what concrete problem it's going to cause, and how you would fix it:

"We make changes directly on the production instance because it's faster. Every Friday, someone exports all the production workflows and uploads the JSONs to the repository, to have a backup just in case."

See solution

The arrow flips from the very first moment: changes are born in the runtime (production), and the repo trails behind, every Friday, copying what production already decided. The source doesn't govern the runtime; the runtime governs the source. The repo isn't a source of truth, it's a delayed mirror.

Concrete problems it causes: (1) there's no review before production —the changes are already live by the time the repo finds out; (2) changes from Monday through Thursday don't exist in the repo until Friday, so a mid-week rollback has nowhere to go back to; (3) if two people change production the same day, the silent overwrite from lesson 3 happens live, on real data; (4) the "backup" repo has good changes mixed in with any urgent improvisation, with no way to tell them apart or explain them.

How to fix it: flip the arrow. Changes are born in dev, get committed to the repo (with review), and get promoted to production. Production stops being where you edit and becomes where you deploy what's been approved. The "Friday backup" disappears because it's no longer needed: the repo is always ahead of the runtime, not behind it.

Why it works: the team's mistake isn't not having a repo —they have one— it's having it on the wrong side of the arrow. Recognizing the direction of the arrow is what distinguishes a repo that's a source of truth from one that's a graveyard of backups. That's this module's central lesson, applied.

Summary and next step

In this lesson you installed the mental model that organizes the whole module: workflow as code. You saw the image of the recipe book and the kitchen —the repository is the master recipe book, the permanent truth; the n8n instance is the kitchen, where workflows run but which is replaceable— and with it you solved the identity question: the "real" workflow is the one in the repository, and the one in the editor is one of several possible executions. You adopted the terms source (the versioned source, the repo) and runtime (where it runs, the instance), and the rule that the arrow goes from source to runtime, never the other way around. You walked through the work cycle —edit in dev, export to JSON, commit to the repo, review the diff, promote to production— following a real order-triage change from start to finish, and you saw that this cycle guarantees, by construction, the four things that make a system owner: never editing production, versioning everything, reviewing everything, and promoting exactly what you tested. And you understood why this frame solves three problems at once —versioning, environments, and testing— because all three are faces of a single idea: separating what the workflow IS from where it RUNS.

Before moving on you should be able to: explain with the recipe book and the kitchen why the repo is the source of truth; name the five steps of the cycle in order; and detect when a team has the source→runtime arrow inverted.

You now have the problem diagnosed and the model that solves it. One piece of honesty is missing before closing the module: how much of all this is free and how much costs money? n8n has version control and environment features built into the interface, but they live in the paid plans. Lesson 7 tells you, with complete honesty, what Community gives you for free —which is, spoiler, everything you need to do what this guide teaches— what Enterprise or Business requires, and the criterion for deciding when it's worth paying. And it gives you a tour of n8n 2.0's interface so you know where export/import and the source control surface live today. It's the lesson that lets you make a money decision with your eyes open.

Resources

• Source control and environments — n8n Docs — n8n's official view on source and environments; useful for contrasting this lesson's conceptual model with the tool's paid implementation.
• Git and n8n — n8n Docs — how n8n conceives the relationship between its instance and a Git repository (in its paid feature): push sends from the runtime to the source, pull brings from the source to the runtime, exactly this lesson's arrow direction.
• Environments in n8n — n8n Docs — the idea of multiple environments backed by Git branches; this lesson's "several kitchens, one recipe" in the paid version.
• Export and import workflows — n8n Docs — the cycle's "export" step, with the tool you already know.