Lesson 0033 · Master Designer · Module 2

Coupling vs Coordination

Decouple two systems and they stop breaking each other — but someone must keep them aligned. Conway's law says the alignment cost follows team boundaries. This is the trade where people are a force.

Reading ≈ 9 minPractice ≈ 30 min

Mission tie-in: the third System Trade-Off — where architecture stops being code-only and starts being about teams.

Knowledge: the two costs

Coupling — two components share a contract: an interface, a schema, a synchronous call. When one changes, the other must change with it. Cost: change amplification (lesson 0006) — a deploy on one side is a coordinated deploy on both.

Coordination — two components are independent, but someone must keep them aligned: versioned contracts, migration windows, compatibility rules, message schemas with both-ways guarantees. Cost: an ongoing conversation that never ends.

You cannot have neither. Zero coupling with zero coordination is two systems that stopped agreeing. The design question is which currency you pay in:

• Coupling pays when the contract is stable: a shared library for a domain concept used by two services, versioned together, deployed together.
• Coordination pays when the sides evolve at different speeds: an event contract (lesson 0025) where consumers tolerate unknown fields and producers keep compatibility.

Conway's law is the tiebreaker: systems mirror the communication structure of the people who build them. A boundary that separates two teams is a coordination boundary whether you design it or not — design it deliberately. And team topologies adds the human cap: every boundary is cognitive load on the teams that must hold both sides of it in their heads.

Coordination only exists if someone writes it down. Here it is as code both sides can run:

# the published contract — the coordination artifact, versioned
@dataclass(frozen=True)
class OrderConfirmedV1:
    order_id: str
    confirmed_at: datetime

def parse_order_confirmed(payload: dict) -> OrderConfirmedV1:
    return OrderConfirmedV1(                        # a tolerant reader
        order_id=payload["order_id"],               # required: removing it breaks us
        confirmed_at=datetime.fromisoformat(payload["confirmed_at"]),
    )                                               # unknown keys: ignored, on purpose

Three rules turn a schema into a contract: producers may add fields and never remove or repurpose them; consumers ignore fields they don't recognise; both sides support N−1 versions for a stated window. A consumer-driven contract test in each team's suite makes those rules fail the build rather than fail in production.

Written down and tested, that is coordination doing its job. Left in a chat thread — "we agreed the field is optional" — it is coordination debt: person-dependent, undiscoverable, and payable at 3 a.m.

Worked: pricing the boundary instead of arguing about it

Checkout (six engineers) calls warehouse (five engineers) for a stock check, synchronously, against a shared schema with no versioning. Every checkout release waits for a warehouse release: two release trains a month, and each one costs two people roughly three hours of sequencing, verification and Slack — 12 person-hours a month, 144 a year, about three and a half person-weeks burned on a runbook line that says "deploy warehouse first".

The first thing a lead looks at is not the diagram; it is git log on the contract. How often has this schema actually changed? Eleven times in twelve months. That number is the whole decision. At eleven changes a year the coupling multiplier is live and the bill is real, so the machinery pays: a written compatibility contract plus consumer-driven tests costs about three days to set up and two hours per subsequent change — 24 hours once, plus 24 hours a year — against 144 hours a year saved. It breaks even in roughly four months. Had the answer been "changed once, in 2023", the same machinery would have been an expensive way to make a stable thing look modern.

The alternative the lead rejects is the popular one: "split them into proper microservices so the teams are decoupled". Rejected because the coupling is not in the deployment unit — it is in the shared schema and the shared concept. Splitting the process without splitting the data ownership adds a network hop, a retry policy and a new failure mode to exactly the same negotiation. Deployment independence is not change independence, and only the second one was costing 144 hours.

The second rejected alternative is subtler: keep the synchronous call but "just version the endpoint". Versions with no stated support window are names, not commitments. Without "we support N−1 for 90 days" written down and tested, both sides still deploy together — you have added ceremony to the runbook and removed nothing from it.

A year on, the difference is visible in what a new engineer has to know. With the contract written and tested, warehouse can ship a field on a Tuesday and checkout finds out from the test suite, not the incident channel; onboarding reads one document. Without it, the alignment lives in the heads of two long-serving engineers, and the day one of them leaves is the day you discover which rules were never rules at all.

When this is the wrong move

Do not buy coordination machinery for a boundary inside one team. When the same six people own both sides and ship on one train, the versioned event contract, the compatibility window and the consumer-driven test suite are ceremony around a conversation that already happens at standup — and worse, they make the cheap move (change both sides in one commit) feel illegal.

Nor should you freeze a contract early. In the first months of a product the model is wrong in ways you cannot yet name; a compatibility document written then locks in that wrongness and charges you a migration every time you learn something. Couple hard, refactor freely, and write the contract when the concept stops moving — the signal is usually a second consumer you do not control.

In the lab: the companion Phase 3 exercise gives you a returns service whose agreement with the order system exists only as field names copied between two modules. You write the compatibility rules down, add a contract test that fails when a required field disappears, and decide out loud which side pays when the two disagree.

Skill: which currency do you pay?

Practice on your own code

Map your system's service boundaries onto your team structure. For each boundary: who changes on each side, who must talk when a contract changes, and is that conversation written down anywhere? The gaps you find are coordination debt — write the compatibility contract.

Read and watch deeper

• Team Topologies, Skelton & Pais — ch. 3–4: cognitive load as the cap on how many boundaries a team can hold, and the four interaction modes.
• "Consumer-Driven Contracts", Robinson on martinfowler.com — the test that turns an agreement into something a build can fail on.
• Conway's law — the original observation, read as a design principle.
• Designing Data-Intensive Applications, Kleppmann — ch. 11: the coordination guarantees (at-least-once, ordering) behind event contracts.
• Watch: ArjanCodes YouTube — search "conway's law" or "team boundaries".
• Next: lesson 0034 — Performance vs Maintainability.
• Reference: Trade-offs — coupling vs coordination; glossary — tolerant reader.

Map your boundaries and teams with your agent-teacher and find the undocumented contracts.