Which Components Must Communicate?
An interface exists wherever two parts must agree on something. Find them by asking, for every workflow step, who has the information and who needs it — the browser, the backend, the database, the payment provider — and you have the interfaces before any of them has a shape.
The situation, the reflex, and why it stalls
Every lesson starts where being stuck starts: someone has a problem, and the first move that comes to mind feels like progress.
You have a list of components and a workflow that crosses them. How do you find every place where two of them must agree — before you design a single endpoint?
I have the store decomposed into catalog, cart, checkout, orders, payments. I know there is a browser, a backend and a database, and that a payment provider is involved somewhere. Now someone says "define the API" and I do not know how many endpoints there are, what talks to what, or where the provider fits in.
Open the API design tool and start listing endpoints. GET /products, POST /cart, POST /checkout. It produces a document quickly and the document looks like the API, and listing resources feels like it will naturally cover everything the store does.
The list has endpoints the browser calls and nothing else, because the browser is the caller you can picture. The backend also calls the payment provider, the provider calls the backend back, and a worker reads the database — none of that is in the list, and each one is an interface with its own contract.
- The list has endpoints the browser calls and nothing else, because the browser is the caller you can picture. The backend also calls the payment provider, the provider calls the backend back, and a worker reads the database — none of that is in the list, and each one is an interface with its own contract.
- The endpoints are named after tables.
POST /ordersexists because there is an Order table; nobody has asked what the browser actually needs to tell the backend at checkout, so the endpoint takes the whole order and the backend trusts prices sent from the client. - The hard question — who tells the backend that a payment succeeded — is not visible in a resource list, so it is not asked. The interface that will cause the most trouble is the one the reflex could not see.
- The document is treated as finished because it is long. Length measured coverage of resources, not coverage of communication, and the two are different.
The move
Precisely enough to apply it to a problem you have never seen — not a slogan.
- Interfaces are found, not invented. An interface exists at every point where two components must agree on something: the shape of a request, the meaning of a status, who decides what. Find those points by walking the core workflow one step at a time and asking two questions at each step: which component has the information needed here, and which component needs it?
- Whenever the answer names two different components, you have found an interface. Write it down as a sentence about communication — "the backend needs to know from the provider whether the charge succeeded" — not as an endpoint. The sentence names the direction, the information and the parties; the endpoint shape is chosen later, and often the sentence rules out the obvious shape.
- Include every direction. Browser to backend is the one everyone lists. Backend to provider, provider to backend, backend to a worker, worker to database, and the database to anything that reads it are all interfaces, and the ones that go *into* your system from outside are the ones that need the most care.
- Then group the sentences by the pair of components they connect. Each pair is one interface, and the sentences under it are the contract's requirements. Now, and not before, the API design domain has something to design.
The interfaces that checkout actually has
The diagram is what the move produces for checkout. Each edge came from a sentence — who has the information, who needs it — and each sentence came from a step in the workflow. The edge the endpoint list did not have is the one from the provider back into the backend, and it is drawn with the same weight as the others because it deserves more.
Nothing on the diagram is an endpoint yet. The shape of each edge — request/response, push, callback — is a decision the sentence constrains but does not make.
From a resource list to a communication list
The reflex asks "what resources exist?"; the move asks "who needs to know what?". The ladder shows the same need asked three ways, and why the last form is the one that produces a contract you can defend.
The best form names both parties, the information, and the direction. It makes answerable the question a resource list never raises: which side decides.
why The best form finds the provider → backend interface and the "who decides paid?" question. The first two forms only ever produce browser-facing endpoints, because the browser is the only caller they can see.
| Interface | Carries | Authoritative side | Shape it rules out |
|---|---|---|---|
| browser → backend | cart id, intent to pay | backend (prices, totals) | browser sending line prices |
| backend → database | reads of price and stock; writes of order and payment | database (current stock) | backend caching stock across the checkout |
| backend → provider | amount, currency, payment token | backend (what to charge) | provider computing the amount |
| provider → backend | charge outcome | provider (whether money moved) | backend deciding "paid" from its own request succeeding |
What the list does not yet know
Finding the interfaces exposes what is unknown about each one. The board keeps those as questions with experiments, because "the provider callback" as a single worry is exactly the vague unknown that gets postponed until it is on the critical path.
- ✓Four interfaces; the browser-facing one is the easiest and the provider-facing pair the hardest.
- ✓The backend is authoritative for prices and totals; the provider is authoritative for whether money moved.
- ~One backend process handles both the customer's request and the provider's callback. If those are ever separate services, the provider → backend edge becomes two edges.
? The provider callback.
becomes Does the provider report the outcome by calling my backend, by my backend polling, or both — and can the same outcome arrive twice?
experiment Read the provider's integration page for the word "webhook" and for its retry policy; then trigger a test-mode charge and count the calls received.
? Realtime for the chat app.
becomes Must Bob's browser be told about a new message, or may it ask — and what does "told" cost in connections held open?
experiment A page that polls every few seconds and a page holding a single open connection, both showing a message the moment it is sent; compare the code each needs.
How to do it
Most important first.
- Take the core workflow from your decomposition (Decomposing Checkout) and, for each step, write who has the information and who needs it. Two names means an interface.
- Write each interface as a sentence with a direction: "A needs to tell B that…" or "A needs to ask B whether…". Verbs matter: *tell* and *ask* have different shapes.
- Draw the components and draw an edge for every sentence. Edges that cross the edge of your system are boundaries, and get their own treatment (Where Does My System End?).
- For each edge, note which side is authoritative for the information carried — the backend for prices, the provider for payment success. An interface where the wrong side is authoritative is a bug waiting for its first user (Source of Truth).
- Only now open the contract question for each edge: request shape, response shape, error shape (Interfaces Emerge From Boundaries).
Worked on a concrete problem
The move has to produce something. This is what it produced.
- Checkout, step by step. "Customer clicks Pay": the browser has the intent and the cart id; the backend needs both. Interface: browser → backend, "here is the cart I want to buy". "Backend validates the cart": the backend needs current prices and stock; the database has them. Interface: backend → database. "Backend charges the card": the backend has the amount and a payment token; the provider needs them. Interface: backend → provider. "Provider confirms": the provider knows the outcome; the backend needs it. Interface: provider → backend, and this one arrives later and from outside.
- Grouped by pair: browser–backend (start checkout, show the result), backend–database (read cart, prices, stock; write order and payment), backend–provider (create a charge), provider–backend (report an outcome). Four interfaces, of which the endpoint list had found one, and the one the list missed — provider → backend — is the one where "who is authoritative for paid?" gets decided.
- The same move on the chat app: "Alice sends a message" — the browser has the text, the backend needs it; "Bob sees it" — the backend has it, Bob's browser needs it, and it has to be pushed rather than asked for. Two interfaces with opposite directions, and the second one is what makes it a chat app rather than a message list.
How you know it worked
What now exists that did not before, and what question you can now ask.
- A list of interfaces exists, each a sentence with two components, a direction and a piece of information, and none of them is yet an endpoint.
- At least one interface points *into* your system from outside — a webhook, a callback, an inbound event — and you can say what it carries.
- For each interface you can name which side is authoritative for what it carries, and at least one of those answers surprised you.
- The endpoint list, when you finally write it, is shorter than the reflex produced and covers more of the workflow.
The questions you can now ask
The field this whole domain exists for. After this lesson, these are the questions to put to an unfamiliar problem.
- ?For this step of the workflow, which component has the information and which component needs it?
- ?Which interfaces point into my system from outside, and what arrives on them?
- ?For each thing carried across an interface, which side is authoritative for it?
- ?Which interface is the one where a wrong answer would be most expensive — and is it the one I was about to design last?
What can go wrong
- Every pair of components gets an interface because they *could* talk. The move finds interfaces the workflow needs, not interfaces the topology permits; an edge with no sentence under it is not an interface.
- The interface sentences are written and the authoritative side is not asked. The list then looks complete while the backend still trusts prices from the browser.
- The move is done once and filed. New workflows — refunds, cancellations — add interfaces, and the provider → backend edge grows new message types; the list has to be reopened when the requirements are.
- On a system with a single process and a single database the move produces one interface and a lot of ceremony. Recognise when there is only one boundary worth the attention.
- Finding interfaces before designing them delays the moment when a frontend developer can start against a contract; on a team that needs to parallelise, that delay is real.
- The sentences are more work than an endpoint list, and for the browser → backend edge they mostly confirm what the list would have said.
- Naming the authoritative side forces a decision — who decides "paid"? — that a resource list would have let you postpone. Postponed is not the same as avoided.
- "So interfaces are the arrows on an architecture diagram." The arrows are where interfaces live; the interface is what has to be agreed across each arrow. A diagram with arrows and no sentences has located the interfaces without discovering them.
- "The database is an interface too, so I should design it like an API." The backend–database edge is an interface, but it is one you own on both sides, and it changes freely; the discipline of contracts belongs to edges where the other side is not you (What an API Contract Actually Is is about the latter).
- "More interfaces means better decoupling." More interfaces means more places to agree. The move is about finding the ones that exist, not about adding ones that do not.
Where this applies
Problem-solving advice is stated as universal far more often than it is. These labels say what each method is specific to — and where CONTESTED appears, the note gives the strongest form of the opposing view.
- GENERALWho-has-it / who-needs-it applies to any system with more than one component: a library and its caller, a compiler pass and the next, a worker and its queue. The vocabulary changes; the two questions do not.
- SCALE-SPECIFICIn a single-process application with one database most "interfaces" are function calls and the move finds one boundary that matters — the provider. The full treatment earns its cost once a second process, a worker or a second team appears.
- ILLUSTRATIVEThe store, the provider and the chat app are invented; the four interfaces found are the shape of the argument, not a specification.
Where the depth lives
This domain asks the question and hands the answer off by name.