A team is about to change the response shape of an internal service and needs to know who will break. They have a maintained context diagram, a container diagram and a component diagram for that service. Which artefact answers the question and why is it none of the three?
Show the full answer Hide the answer
The deciding property
Every diagram in a layered set is drawn from the point of view of the system in scope. Its edges record what that system calls. Nobody updates your diagram when they start calling you, so inbound edges are structurally incomplete in a way outbound edges are not — not because teams are careless, but because the artefact has no mechanism for a stranger to add themselves to it.
A change to a response shape is an inbound question. The number of callers is unbounded and discovered, not designed.
Why a consumer register
A register is a list, refreshed from evidence, with one row per caller: the caller's name, its owning team, the fields it reads, the version it is pinned to, and when it was last seen. The field list is the part that turns the register from a contact sheet into a change-safety tool, because removing a field only breaks the subset of callers that read it.
Derive the rows from four places rather than from memory: gateway or mesh access logs grouped by caller identity over 30 days; the service's own request logs with a client identifier; declared dependencies in other teams' manifests; and consumer-driven contract tests if they exist. A caller absent from 30 days of logs and present in a manifest is the dangerous case — a monthly batch job that will break three weeks after the change ships.
Why not the other options
- A deeper component diagram. It adds internal detail about the thing being changed. The risk is entirely external, so more zoom moves away from the answer. This is the common instinct and it is why teams keep producing component diagrams nobody reads.
- The context diagram redrawn with this service in the centre. Closer, and it captures known consumers at the point someone last drew it. It records relationships that were designed. A register records relationships that happened, with a last-seen date, which is the difference that matters here.
- A sequence diagram of the common path. Shows ordering and failure behaviour for one interaction. It names the participants in that interaction only, so it answers "what does this flow depend on", not "who depends on me".
What would flip the decision
| If this changes | Choose | Because |
|---|---|---|
| The service is public with unknown clients | Versioned endpoint plus a deprecation window | You cannot enumerate the consumers at all |
| Fewer than five callers and all in one team | A conversation and a diagram | The register's cost exceeds its value |
| Callers are pinned to a schema registry | Compatibility mode on the registry | The registry already rejects the unsafe change |
When this is the wrong answer
If the change is additive — a new optional field — the register is unnecessary, because compatible changes break nobody. Spend the register's effort only on removals, renames, type changes and semantic changes to existing fields. Keeping a register for additive changes trains the team to ignore it.