Short answer
#What it is
- Integrations map
- A record of the external interfaces a system uses and exposes: which component talks to which outside service, in which direction, through what kind of interface, for what purpose — together with what could not be established about each.
- In plain terms Everything outside your software that your software needs in order to work, and how it reaches each one.
#Why the list is always incomplete
Ask three people in a company for the list of external dependencies and you will get three different lists, none of them complete.
The reason is structural rather than careless. Dependencies accumulate one at a time, each added by one person for one reason, at a moment when it was obvious and did not need writing down. Four years later:
- the person who added the SMS provider has left;
- the analytics integration is called from one file nobody opens;
- the internal reporting API belongs to a team that has since been reorganised;
- the object storage bucket is referenced by an environment variable whose value nobody has looked at since it was set.
None of that is visible from the outside, and none of it appears in a conversation, because the whole category consists of things nobody thinks of. It becomes visible in exactly two circumstances: when one of them breaks, and when somebody derives the list from the system instead of from memory.
#What counts as a dependency
| Kind | Examples | What its failure looks like |
|---|---|---|
| Paid third-party service | Payments, email delivery, SMS, maps, address lookup | A business function stops. Usually visible immediately. |
| Infrastructure service | Object storage, managed database, queue, cache, search | Broad and severe. Often the hardest to replace. |
| Identity | Single sign-on, OAuth provider, an identity platform | Nobody can log in, including you. |
| Internal API of another team | A reporting service, a shared customer record | Slow, political, and invisible until it happens. |
| Outbound integration | A nightly file to a partner, a webhook to a client | Silent. Somebody else notices first, weeks later. |
| Inbound interface | A public API, a webhook you receive | Somebody else's product breaks, and you own the fix. |
The last two are the ones most often missing from a company's own list, because they do not feel like dependencies. They are: something outside is relying on an agreement, and neither side has written it down.
#The five questions per entry
The map answers the first three from the system. The other two are for a person, and are usually the expensive ones.
-
What is it, and what is it for?
The name of the service and one sentence about what stops working without it.
-
Which part of our system touches it?
Which components, through which interface, in which direction.
-
How does it behave?
How it authenticates, whether there is a timeout, whether there are retries, whether repeating a request is safe.
-
Whose account is it?
Not derivable from code. If the answer is “our developer's personal account”, you have found something important.
The agency dependency and handover readiness tools ask this one directly.
-
What happens if it stops?
A judgement, not a fact — but one nobody can make until the first three questions have answers.
#What one looks like
OUTBOUND Payment provider REST · external
from Billing service
auth API key from configuration
for Taking card payments
⚠ Retry behaviour not established
OUTBOUND Transactional email REST · external
from Notification module
for Receipts, dunning notices, password resets
OUTBOUND Object storage SDK · external
from Invoice renderer
for Storing generated invoice PDFs
⚠ Bucket and region come from configuration outside
the repository — not established
OUTBOUND Partner CSV drop FILE · external
from Nightly export
for A daily payments file
⚠ Destination not established. Nobody in the analysis
could say who receives this.
INBOUND Payments API REST · public
to Billing service
for Letting the storefront take a payment
auth Bearer token issued by the storefront
INBOUND Provider webhook REST · external
to Billing service
for Confirming a payment settled
⚠ No authentication of the sender was establishedFour warnings out of six entries, which is a realistic ratio for a first analysis of a real system. Two of them — where the nightly file goes, and whether the provider webhook checks who sent it — are things an owner should want to know today, and neither would come up in a conversation about architecture.
#Dependency is not the same as ownership
A map can establish that your software calls a payment provider. It cannot establish whose account that is, and that second question is the one that decides how much trouble you are in.
The pattern worth looking for: a dependency your system needs, held in an account your company does not control. A cloud project on an agency's organisation. A domain registered to a developer's personal email. A payment integration on a supplier's merchant account. Each of these is invisible in the code, entirely normal in origin, and a serious problem at exactly one moment.
Two things on this site deal with that directly: who should own production infrastructure, and the agency dependency check, which walks through the accounts one at a time.
#What it cannot find
What this does not do
- Anything that exists only in a cloud console. If no code refers to it, an analysis of the code cannot see it. It can only tell you that a configuration value is used and that its meaning was not established.
- Who pays for what. Billing relationships are not a property of software.
- Whether a contract exists. A supplier your system depends on with no agreement behind it looks identical to one with a five-year contract.
- Rate limits, quotas and commercial terms. Sometimes visible in code as constants; usually not.
- Shadow dependencies added at runtime — a plugin loaded from configuration, a URL supplied by an environment variable. These surface as unknowns rather than as entries.