Wardley Mapping: Build vs Buy Decisions as Code

Last week I sat in a keynote by Simon Wardley, an introduction to the mapping technique that carries his name. I knew about Wardley Mapping and had never drawn one. Early on he put up an ordinary systems diagram, the boxes-and-arrows kind every one of us has in a slide deck somewhere, and said that it does not represent the architecture of the system. "It represents a belief." It shows what we hope the system looks like. The code, he said, is the architecture: "the collection of all the decisions we've actually made."

I partly disagree, and I will come back to why. I remember the line because of where he took it. He closed by saying the future of systems architecture "is all about deciding who makes what decisions and where." That is a statement about judgement, and judgement is exactly what our diagrams are bad at showing. A box diagram tells you what talks to what. It says nothing about which of those boxes you should still be building yourself.

A Wardley map is a belief too. The difference is that it is explicit, shared and positioned, so you can point at a component and say it sits in the wrong place. This post covers what a map is, why resistance to change keeps components stuck on the wrong side of it, and how to draw your first one as a text file that lives in your repository next to your ADRs.

The Restaurant With No Front Wall

Picture a restaurant drawn with the front wall removed, so you can see every level. The guest sits at the top, at the table, wanting a finished meal. Below the dining room is the serving counter, then the cooking area, then the storage room and the dishwashing room at the bottom. The further down you go, the less the guest sees or cares. Nobody at the table has ever asked about the broth, yet the dish needs the sauce, the sauce needs the broth, and the broth needs bones and a gas stove. That chain from top to bottom is the visibility axis.

Now spread the kitchen out from left to right: the wild plant the chef found and is still testing, the dishes made by hand every morning, the packaged products bought from a supplier, and on the far right the water and gas from the public network, which nobody in the kitchen has ever thought of making. That is evolution. And things move. The day a supplier starts selling good fresh pasta, the hand-made pasta station moves right whether the kitchen likes it or not. The chef who has rolled pasta for twenty years and refuses to stop is resistance to change in person. On the kitchen wall hangs a sheet that says, for each item: make it, buy it, or use a public service.

A Wardley map is that picture for your system: how far each component sits from the user, how evolved it is, and therefore what you should do with it.

A Wardley Map Is Also a Belief

Wardley's keynote started with a claim about diagrams, and I agree with half of it. Every diagram shows what someone believes about a system, and a Wardley map is no different. What sets it apart is that it follows rules, so you can test the belief. This section covers what those rules are, and where I disagree with the keynote.

Why Most Architecture Diagrams Are Graphs

Wardley's test for a map is simple. It needs an anchor (the user need), position, and consistent movement. Move a box on a systems diagram and nothing changes, so most of what we call maps are really graphs. On a Wardley map, sliding a component left or right changes what you are claiming about it.

The horizontal axis runs through four stages: genesis, custom-built, product (and rental), and commodity or utility. Agile-style methods suit the left, lean and off-the-shelf suit the middle, and on the right you outsource to a utility. A single contract mixing all three, Wardley warned, will fail. I have argued before for reuse over custom code as a fixed ladder of build, buy and reuse. The map adds what that ladder lacks: the right step for a component changes over time.

Where I Part Ways With the Keynote

I accept that a diagram is a belief. I do not accept that the code is therefore the architecture, for three reasons.

Intent lives outside the code. A diagram or decision record captures why we chose something and what we chose not to do. Code also works at too low a level. A tangle of functions is nothing a stakeholder can reason about, and hiding detail is the point of an architecture. Most of all, not everything is code. Contracts, SaaS subscriptions, vendors, teams and processes are all part of the architecture, and none of them ever show up in the codebase.

A Wardley map holds all of that, and a vendor contract is as easy to place on it as a microservice. It is still a belief, just one laid out on the table.

Past Success Makes Change Hard

Wardley told a story about an insurer that was planning to spend millions on robots to change servers so they would fit its custom-built racks. Fifteen minutes of arguing got nowhere. Fifteen minutes of mapping later, someone asked why they were not simply using standard racks, and the project disappeared. In his words, they "were simply trapped by past narrative," which means the old story about why things were built that way. Wardley calls this inertia: past success breeds resistance to change.

I have my own version of that story. I was involved in a custom business process management application that cost a lot to build, mostly because of the customisations. Those were deliberate. Ways of working on manual tasks were spread across the organisation, and the customisations were there to get users to accept the new system. The plan was to use that acceptance as a base and slowly move towards a standard, simpler, automated way of working.

That move happened, partly. The reasoning at the start was sound. On a map, though, the customisation made the platform hard to move to the right, even though a process engine is something you can buy.

Drawing Your First Wardley Map in Code

Here is a map for that kind of decision, built for an order-approval workflow. It uses OnlineWardleyMaps, which turns plain text into a map in the browser. There is nothing to install. Coordinates are [visibility, maturity], both from 0 to 1: visibility 1 is the top of the map, maturity 0 is genesis and 1 is commodity.

Step 1: Start an Empty Map With an Anchor

Every map starts from a user need, so create the file first and write the anchor before anything else. Open onlinewardleymaps.com, clear the editor, and keep a copy of the text in your repository as you go.

mkdir -p docs/maps
touch docs/maps/order-approval.owm

title Order Approval Platform
style wardley

anchor Approver [0.95, 0.63]

You should see an empty map with its evolution stages along the bottom and a single anchor, Approver, near the top.

Step 2: Draw the Value Chain

Add the components the approver depends on, placed by how visible they are to the approver and how evolved you believe they are. Add the links last. Be honest about maturity here, because this is where the argument will happen.

component Order approval [0.85, 0.45]
component Approval workflow [0.72, 0.38]
component Business rules [0.62, 0.22]
component Forms [0.55, 0.6]
component Process engine [0.45, 0.3]
component Notifications [0.38, 0.78]
component Identity [0.3, 0.72]
component Database [0.18, 0.8]
component Compute [0.08, 0.92]

Approver->Order approval
Order approval->Approval workflow
Approval workflow->Business rules
Approval workflow->Forms
Approval workflow->Process engine
Approval workflow->Notifications
Forms->Identity
Process engine->Database
Database->Compute
Notifications->Compute

The map now shows a chain running from Approver down to Compute. Process engine sits in the custom-built band, which is exactly where our BPM platform ended up.

Step 3: Mark What Resists Change

Next, say out loud what is holding a component in place. The map keyword for this is inertia. Replace the component Process engine line from Step 2 with the first line below, replace the Step 2 link line Approval workflow->Process engine with the labelled one, and add the note. The file should hold each component and each link once.

component Process engine [0.45, 0.3] inertia
Approval workflow->Process engine; customised per team
note Every team's manual process built in for adoption [0.5, 0.05]

You should see a bar next to Process engine that shows the resistance to change, the label on its incoming link, and the note on the far left.

Step 4: Evolve and Decide

This is the make-or-buy sheet from the kitchen. Mark where the market has moved and what you will do about each component. Replace the existing Business rules, Database and Compute lines with the versions below, keep the Process engine line with inertia from Step 3 as it is, and add the evolve line.

component Business rules [0.62, 0.22] (build)
evolve Process engine 0.62 (buy)
component Database [0.18, 0.8] (outsource)
component Compute [0.08, 0.92] (outsource)

You should see a red arrow from Process engine to its future position in the product band, with the resistance-to-change bar now on that arrow. Business rules gets a light circle for build, and Database and Compute get a dark circle for outsource. The (buy) on the evolve line draws no marker, but it records the decision in the file. The decision the map makes visible: build the business rules, which are where your approval logic is actually specific to you, and buy the engine underneath them.

Step 5: Commit It Beside the ADR With a Redraw Trigger

A map that lives in a slide deck becomes out of date without anyone noticing. Put it next to the decision it supports, review it like an ADR, and write down what should make you redraw it.

<!-- docs/adr/order-approval-platform.md -->
## Map
docs/maps/order-approval.owm

## Redraw trigger
Redraw the map when a component we build becomes available as a product,
when a team asks for a new customisation to the process engine,
or at the next contract renewal for any bought component.

git add docs/maps/order-approval.owm docs/adr/order-approval-platform.md
git commit -m "Add order approval map and redraw trigger"

git status should come back clean, with one commit holding both files. There is nothing to tear down. The browser editor holds nothing you need, and the file in your repository is the map.

Make, Buy, or Plug In

Stage	In the kitchen	In the order-approval map	What to do
Genesis	Wild plant, still a test	Nothing yet	Explore, agile-style
Custom-built	Pasta made by hand	Business rules	Build, agile-style
Product (and rental)	Packaged product from a supplier	Forms, and Process engine once evolved	Buy, lean and off-the-shelf
Commodity / utility	Water and gas from the public network	Database, Compute (also Identity, Notifications)	Outsource to a utility

Challenge the Map, Not the Person

The second line from the keynote that I remember was this one: "Once you have a map, you can challenge the map, not the person." Leaders tell stories, so challenging the story feels like challenging the leader. A map takes the story out of someone's head and puts it on the table, where moving a box is an argument about the box.

• An anchor, position and movement separate a map from a graph.
• Position is a claim. If moving a component would not change the decision, you have drawn a diagram.
• Resistance to change deserves its own label. Write down why a component is stuck, or it stays stuck without anyone noticing.
• Different stages, different methods. Do not run custom work and utility work under one contract.
• Keep the map in the repository beside the ADR, with a trigger that tells you when to redraw it.

This order-approval map is the first one I have drawn for a real decision. Starting custom was the right call for that BPM platform. A map with an inertia marker and a redraw trigger might have shown when it stopped being one.

Which component in your system is the chef who will not stop rolling pasta? And most importantly, when was the last time anyone was allowed to say so?