Modelling the system before the code

When does an order exist? Sales may say when the customer agrees. Finance may say when payment clears. Fulfilment may say when stock is reserved. If all three teams use the same status field, a small naming problem can become a costly system problem.

I want those differences on the table before they become database fields and API rules.

One word, four contracts

People rarely announce that they mean different things. Each team uses the language that works for its part of the job. A shared model gives them a way to compare those meanings.

Before adding an “order status”, ask what each state allows someone to do. Can Finance take payment? Can Fulfilment reserve stock? Can Support promise a delivery date? Those answers define the behaviour the software must support.

Use the model to work through disagreements

Map the process, the information it uses, the decisions people make and the handoffs between them. Walk through a real case with business and technical colleagues. When someone says “That is not how it happens”, follow the difference.

Changing a definition during that conversation is usually easier than changing code, stored records and integrations built around it.

What to actually map

I use four passes to understand the operation:

1. Events. What happens, in the language the business already uses. "Order placed", "payment cleared", "shipment dispatched". Past tense, because events are facts.
2. Decisions. Where a judgement is made, and who makes it. Every decision is a place the process can branch, stall, or need an exception.
3. Information. What each step needs to know, and where that knowledge lives. This is where duplicated, drifting copies of the truth become visible.
4. Boundaries. Where responsibility changes hands. Boundaries drawn here become the seams in the architecture later, so it is worth arguing about them now.

Starting with events keeps the discussion close to work people recognise. Tables and services can follow once the meanings and responsibilities are clearer.

What a good model makes obvious

The model should help the team answer:

• Where one responsibility ends and another begins.
• Which pieces of information have a single owner, and which are copied around and drifting.
• Where a process depends on a step that no one is actually responsible for.

Any gap deserves an owner and a decision before implementation depends on it.

How it goes wrong

Watch for four ways the exercise can lose its purpose:

• Review becomes a sign-off exercise. Ask people to test the model with cases, not simply approve the document.
• Modelling the software instead of the work. If the boxes are services and the arrows are API calls, you have drawn the solution and skipped the problem.
• Only technical people in the room. The whole value is in surfacing the disagreement between functions. A model built by engineers alone reproduces the engineers' assumptions faithfully.
• Detail keeps growing without a decision. Resolve the expensive assumptions, then build a small part of the system and learn from its use.

TASK
Prepare a shared order model from these fictional department notes.

[S1 SALES] “Confirmed” means the customer accepted the quote. Sales records that
agreement but cannot verify payment or reserve inventory.
[F1 FINANCE] “Confirmed” means payment is received. Finance records payments and
refunds; a paid order may still have unavailable stock.
[W1 FULFILMENT] “Confirmed” means stock is reserved. Fulfilment reserves and ships
stock but does not decide whether a payment can be refunded.
[P1 POLICY] Dispatch requires customer agreement, payment received and stock reserved.

OUTPUT
A glossary that gives the three facts distinct names; a fact/event/owner table;
a small flow showing the dispatch gate; and the unresolved policy decisions.
Use S1, F1, W1 and P1 as evidence. Show which facts can occur in either order.
Do not collapse independent facts into one linear “confirmed” status.

CHANGED CASE
The customer cancels after payment, before dispatch, while stock is reserved.
Identify the decisions, responsible roles and records needed to coordinate
cancellation. Do not invent the refund policy or assume a refund already happened.

Agreed before implementation, not instead of it

You do not need to settle every detail before building. Agree the important meanings, responsibilities and constraints, then implement a small complete path.

Watch people use it. Add the missing cases and revise the model with them. Keep it close enough to the software that it still helps with the next change.

See the concrete outputs and indicative planning range for a TreeNodes systems design engagement.