There is a question that stalls almost every incident I have been part of, and it arrives about four minutes in.
Something is failing. You have found the service responsible. Then somebody asks what else touches it, and the room goes quiet. Two people offer partial answers. One of them is out of date. Somebody pulls up a diagram, looks at it for a moment, and says it is probably not current.
The data to answer that question exists. It is in your traces, your service configuration, your code, your deploy history. It is simply not assembled anywhere, so the answer has to be reconstructed from memory under time pressure by whoever happens to be awake.
Diagrams describe intent
An architecture diagram is a record of what somebody meant to build, drawn at a moment when that was still true.
The system then keeps moving. A service is split. A queue is removed. A team takes on an integration that was meant to be temporary. None of these events generate a diagram update, because updating the diagram is nobody's job in particular and it never blocks a release.
One engineer writing on dependency mapping described spending hours with diagrams that were out of date before the ink dried, and that has been my experience too. The document is not wrong because anyone was careless. It is wrong because it was a snapshot competing against a system that changes daily.
A piece on documenting microservices puts the state of it well: there is documentation, technically. A wiki page from last year. A diagram exported before the last reorganisation. A README still naming a queue the team deleted months ago. During an incident, the on-call engineer knows where the request enters, and cannot say with confidence which service owns the transformation in the middle or which downstream call is synchronous.
The dependencies nobody wrote down
The gap is worst where it matters most, which is the connections that were never deliberate.
Service-to-service calls that were added for one feature and quietly became load-bearing. Third-party APIs that got wired in on the assumption they would always be available. Async edges through a message broker, which almost never appear on a diagram at all because the calling code does not look like a call.
Ownership metadata decays the same way. Teams reorganise, people move, and the tag stays. The practical consequence is alerts routing to a team that has not owned that service in eight months, which costs you the first fifteen minutes of an incident before anyone has looked at a graph.
A map should be derived, not drawn
This is the part I have become fairly firm about.
Any map maintained by hand decays at exactly the rate your system changes, and it decays silently. You do not find out it is wrong when it becomes wrong. You find out during the incident that made you look at it.
The alternative is to derive the map from the systems that already know. Your repositories know what calls what. Your CI system knows what deploys where. Your traces know the actual request path, including the parts nobody documented. Your cloud provider knows which resources exist and how they are wired. None of that requires anybody to remember to update anything, because it is a by-product of the system running rather than a separate artefact somebody maintains.
Derived maps have their own failure mode, and it is worth naming: they show you what is happening, not what is supposed to happen. A dependency that exists by mistake looks identical to one that exists by design. That is a real limitation, though I would rather have an accurate picture of a messy reality than a tidy picture of something that is not true.
The failure that happens before the investigation starts
I work at Frigga on Vörr, which builds this kind of derived view across code, cloud and monitoring, so treat what follows as an interested opinion.
The design decision I find most quietly useful is not the graph itself. It is that Vörr can enumerate the real names that exist, so nothing in an investigation has to begin with a guess.
That sounds minor and it is not. Watch how investigations actually start. Somebody types a service name from memory, or a slightly wrong variant of it, or the name it had before the rename. The query returns nothing. Now you are debugging your own search rather than the incident, and worse, an empty result reads as reassuring. Nothing came back, so nothing must be wrong.
Being able to list what genuinely exists, and getting an honest answer about which underlying system holds each thing, removes a whole category of wasted minutes at the exact point where minutes are expensive. It also means that when a query does come back empty, you can trust the emptiness.
Three things worth doing regardless of tooling
Ask the blast radius question cold, outside an incident. Pick a service and ask a colleague what breaks if it stops. Time the answer. If it takes more than a few minutes, you have found the gap, and you found it on a Tuesday afternoon rather than at two in the morning.
Keep ownership next to the code. A field in a manifest file in the service's own repository stays current far better than a central registry, because it sits where people are already working and it goes stale visibly.
Then stop maintaining anything you can derive. Diagrams are still worth drawing for design conversations and for explaining intent to a new hire. They are not worth trusting during an incident, and the effort spent keeping them current is better spent making the real topology readable.
Your system already knows how it is wired. The problem was never a lack of information. It is that the information lives in six systems and the only place it has ever been assembled is somebody's head.
Author note
Mohan Gopi, Associate DevOps Engineer at Frigga Cloud Labs.
I have never fully trusted an architecture diagram I did not draw myself that week, and I have stopped treating that as cynicism. Most of what a team knows about its own system lives in people's heads, and people move on. If your map is only as current as the last person who remembered to update it, it is not really a map.
I would be interested to hear how other teams handle this, particularly anyone who has made a service catalogue stick without it becoming a second job. Find me on LinkedIn.