Domain seams: where systems quietly come apart.

A seam is a place in a system where two domains are joined. In a healthy system, the seam is named, contracted, and owned: there is a service boundary, a published interface, a person whose job it is to evolve it. In a system that has accumulated for fifteen years, the seam is still there — but its name, contract, and owner have all drifted, and nobody quite agrees on where the line is.

The behaviour around a misnamed seam is unmistakable once you know to look for it. Every change becomes a meeting. Every release requires a coordinator. Every estimate carries a tax that nobody wants to itemise. The system is not technically broken; it is institutionally arthritic, and the arthritis has settled at the joints.

How seams drift

Seams drift in three common ways.

The first is silent overlap. Two domains begin sharing data — usually a database table, sometimes a queue or an internal API — that neither owns. Each domain has a reasonable claim to it. Each is therefore reluctant to evolve it independently, because the other will be affected. Over time, the overlap becomes the slowest part of the system to change, because every change requires consent from both sides.

The second is shadow ownership. The original owner of the seam moved teams, was promoted, or left the company. The seam has been adopted, in practice, by an engineer or team who had nothing to do with its design. They maintain it because somebody must, but they do not feel authorised to change it. The seam is technically owned and politically un-owned.

The third is erosion. The original contract was clear. But over the years it accumulated exceptions — small accommodations to specific callers, edge cases that needed to ship, behaviours that emerged after the contract was written. None of the accommodations were documented. The contract on paper now describes a system that no longer exists.

Why naming matters

The single most useful artefact we produce in any discovery engagement is a named map of the seams. Not a list of services. Not an architecture diagram. A document that says, for each significant boundary in the system: this is the seam, this is what passes across it, this is who owns each side, this is what the contract is supposed to be, this is how the contract has drifted.

The act of writing this document is often the first time the organisation has agreed on the answers in years. The discussions that produce it are sometimes uncomfortable; the document itself is rarely surprising. What is surprising is that nobody had written it down.

“

The map is not the territory, but in legacy systems, the territory has been moving for so long that any map drawn carefully is enormously valuable.

”

Three signals

When we walk into a system we have not seen before, three signals tell us almost immediately where the seams have drifted.

Tickets that touch many teams. If the average ticket in your system requires coordination across more than three teams to ship, the seams have drifted. Healthy boundaries make most work tractable inside a single team.

Estimates with implicit reserves. Engineers building near a drifted seam consistently over-estimate by a multiplier that everyone accepts and nobody discusses. The multiplier is real. It is the cost of negotiating the seam, and it is paid in every estimate.

Postmortems that name the same join twice. Recurrent incidents at the same boundary, with different proximate causes, almost always indicate a structural problem at the seam rather than a series of unlucky bugs.

If you see two of these three, you have at least one drifted seam. If you see all three, you have several.

The work of re-naming

Re-naming a seam is not, primarily, a technical exercise. It is an organisational one. The technical changes — extracting an interface, splitting a database, formalising a queue — are downstream of the agreement. The agreement is the work.

We approach this in stages. The first stage is to describe the current state, plainly and without judgement, in language that the involved teams will recognise. This is harder than it sounds; the natural temptation is to describe the system you wish you had rather than the one you have.

The second stage is to propose the boundary. Where, precisely, does the line go? What is on each side? What flows across? A good proposal is concrete enough that engineers on both sides can reach for the same example and trace it through.

The third stage is to agree the contract. This is where most re-naming exercises succeed or fail. The contract is not the API; it is the deeper question of who is permitted to change what, on what cadence, with what notice. Get the API right and the contract wrong, and the seam will drift again within two years.

The fourth stage is the migration itself, which is usually anti-climactic if the first three stages have been done well. If the migration feels surprising, the agreement was not deep enough.

What seams cost when they go un-renamed

It is hard to quantify the cost of un-renamed seams in advance, but we have a rule of thumb. In the engagements we have done, the cost of carrying a single drifted seam for one year is roughly equal to the cost of a senior engineer for one quarter. The cost of carrying three drifted seams is greater than the sum of the parts, because they interact.

This is not the cost of fixing the seams. It is the cost of not fixing them — the meetings, the multipliers, the postmortems that recur, the cautious refusal to change anything because nobody quite knows what will break. The fix is almost always cheaper than the carry.

A small piece of advice

If you suspect you have a drifted seam in your system but cannot point to it, try the following exercise. Pick any change that has felt expensive in the last three months — anything that took longer than its initial estimate suggested it should. Trace the work in detail. Note every time the work crossed a team, a service, or a code boundary. Note the moments where the next step required someone to ask permission.

The map of those moments, drawn carefully, is almost always the map of your drifted seams. The exercise takes a single afternoon. We have never run it without learning something.

The point of all this is not that legacy systems are bad. They are usually the most valuable software an organisation owns. The point is that the seams are where their value is most fragile, and that the work of keeping the seams named is the work of keeping the value compounding.

It is also some of the most quietly important engineering work that exists. We think it deserves more attention than it gets.