Context & scope — the boundary and what crosses it

Inside is what you can modify, deploy and roll back on your own cycle. Everything else is context. Not ownership, not network location, not whether the same company pays for both — the test is whether you can change its contract and release the change yourself.

Which means another team's service in the same cluster is external. You cannot alter its interface, you cannot roll it back, and you learn about its incidents roughly the way its other consumers do. Teams that draw the boundary around the company instead of around the deploy unit end up with a context diagram that omits the dependencies most likely to page them.

Scope follows the same rule and adds one thing: it is defined as much by what you refuse as by what you build. A boundary that has never rejected a responsibility has not been drawn yet.

What crosses — data, events, files, money. Who initiates, because inbound and outbound fail in different ways and need different defences. What the exchange costs you in latency, money and coupling. And what happens when it lies.

Most context diagrams answer the first and imply the second. The third is what makes a design argument possible: an exchange that adds 300ms to a synchronous path or a per-call fee to every request is a fact the strategy has to respond to, and it is invisible on a diagram.

The fourth is the one that turns into an incident. Not "when it is down" — that case is obvious and usually handled — but when it returns stale data, wrong data, a 200 with an empty body, or a timeout that your client records as a success. Write the answer per system, because it differs: some exchanges should fail the request, some should degrade, some should queue, and a few can be ignored entirely.

List the systems you deliberately do not integrate with, the responsibilities you are not taking, and the data you deliberately do not hold. Three lines, and they prevent the most expensive category of late surprise.

The cost of leaving it out is a sentence everyone has heard: we assumed you were doing that. A stakeholder's mental model expands to fill any space the spec leaves empty, and the discovery usually arrives during integration testing, when the boundary is already load-bearing.

Not holding data is also an achievement, not an omission. A system that has never stored a card number or a national identifier has a smaller compliance surface for that reason alone — record it, or someone adds a convenient column and nobody notices the boundary moved.

Anything you cannot deploy is at best semi-trusted, wherever it sits on the network. Trust granted by location is how one malformed upstream payload becomes your data-corruption incident: the validation was skipped because the caller was inside.

So validate at the boundary, in one place, and keep their model out of yours. An anti-corruption layer is not ceremony — it is what stops an upstream's field names, enum values and idea of a customer from spreading through your domain and making their next breaking change your migration.

Every synchronous dependency on the critical path multiplies into your own availability. Three vendors at 99.9% in a request path cap that path near 99.7% before your code contributes a single failure, and no amount of internal engineering recovers it. That arithmetic belongs next to the quality goal it constrains.

Record both numbers per system: the availability the vendor publishes and the one you observe. They differ, and the observed number is the one your users experience. The gap is also the strongest argument you will ever have for moving a dependency off the synchronous path.

Another team's service, the database two teams still share, the platform's ingress, the internal identity service. These get left out because they feel like us rather than them, and they behave exactly like third parties: independent release cycles, their own incidents, contracts you cannot change unilaterally.

Write them down with the owning team named. The name is the field that gets used — during an incident, and during the six weeks before a breaking change, when the only thing standing between you and a surprise is knowing who to ask.

Three independent providers, one shared identity provider underneath. Two regions, one control plane. A queue and a database in the same availability zone. Redundancy on a diagram is not redundancy in a failure, and the shared upstream is invisible at your boundary.

Note it where you know it. You will not map every transitive dependency, and you do not need to — the value is in the two or three cases where the thing you called redundant has a single point of failure one hop down.

Traces, service maps and dependency graphs come free with any competent observability stack, and they are better than a hand-drawn diagram because they cannot be out of date. Let the tooling own the picture.

What no tool infers is the part that matters: what the exchange costs, what the contract obliges, whether the data may leave a region, who to call, and what to do when the response is wrong. Generate the graph, and spend the time you saved on the four columns.

The invented endpoint is the visible failure and the least expensive one. The costly version is subtler: the agent picks the wrong one of two real systems, or calls the vendor SDK directly from the domain when an adapter already exists three directories away. Both look correct in review.

An enumerated list — ids, systems, direction, and the one interface path each is reached through — makes the right choice the obvious one, and it is small enough to sit in every session rather than be fetched when someone remembers. The agent is also good at maintaining it: finding calls that bypass an interface, systems present in code but absent from the list, entries with no failure policy.

One declared path per external system, and every call to it lives there. That is a rule a build can check — an import boundary test, a lint rule, a dependency-cruiser config — which turns a line of prose into enforcement.

This is the same move the guardrails concern makes generally, and it pays double here. It stops the vendor SDK spreading into four modules, and it gives an agent a single, unambiguous answer to "where does this call go", which is the question it otherwise answers by inventing a location.

Timeouts, retries, idempotency and degradation are architecture, not code style. Absent a stated policy an agent writes something plausible, and plausible defaults are where the outages live: a retry loop on a non-idempotent write, an infinite backoff on a user-facing path, a swallowed error that records an empty response as truth.

One enum per entry — fail, degrade, queue, ignore — removes the guess. It is four characters of spec that decide whether a generated client is safe, and it is the field a reviewer can check without holding the whole system in their head.

A model provider is an external system like any other, and it breaks the columns in unfamiliar ways: non-deterministic responses, per-call pricing that scales with usage rather than with capacity, versions that change underneath you, and latency measured in seconds.

The trust field is the one that matters most and is most often skipped. Text returned by a model, flowing into a tool call, a query or a template, is untrusted input crossing your boundary — whatever the arrow on the diagram suggests about direction. Treat the model's output the way you would treat a request body from the public internet, and record it as such, because an agent reading the spec will otherwise reasonably conclude that a system your own code called is a system your own code can believe.