Dependency map: what you need to know before any migration
System migrations fail not because of technical complexity but because of hidden dependencies. I explain how to build a dependency map and why it is work that must happen before the project starts.
I have seen many migrations that started on schedule and ended several months late with a budget twice what was planned. Almost every time the reason was the same: dependencies were discovered mid-project that nobody had known about in advance.
This is not a question of poor planning in the usual sense. It is a question of not having a map of what exists.
What a dependency map is
A dependency map is a description of how the systems and services in a company are connected. What each system consumes, what it produces, who it interacts with and how.
In a small company this can be a table with a few rows. In a company with mature IT infrastructure it is a graph of dozens of nodes with different types of connections: synchronous API calls, asynchronous queues, file exchanges, manual data operations, scheduled jobs.
The problem is that this map almost never exists in an up-to-date form. It was either never created, or was created long ago and has drifted.
Why dependencies stay invisible
The first reason is that systems were added gradually, and each integration felt like a local decision. Nobody updated the overall diagram because there was no overall diagram.
The second reason is that some dependencies are informal. One service reads a file that another service deposits there. This is documented in no API contract, but the system relies on it.
The third reason is that people leave. The person who remembered why system A and system B are connected through an intermediate database table left the company years ago.
How to build the map in practice
I do not recommend trying to build a complete map of everything at once. It is expensive and almost never gets finished.
A useful approach is to build the map around the specific object of change. If replacing a payroll system is planned, start with the question: who else reads data from this system? Who writes to it? What happens to those consumers when the system changes?
This gives a limited but current dependency graph that is sufficient for planning.
The practical method is a series of short interviews with owners of adjacent systems and with data analysts. Analysts usually know the hidden dependencies better than anyone, because they are the ones who deal with the consequences when something breaks.
Questions to ask before you start
Before approving the budget and timeline for any migration or system replacement:
- Is there a list of all consumers of the data this system produces?
- Are there dependencies that are not formally documented but exist in practice?
- Who in the company knows these hidden dependencies, and are they available to participate in the project?
- Is there a plan for each dependency during the migration period?
- Who will verify that all consumers are working correctly after the migration?
If these questions are not asked before the start, they will be asked in the middle. But the cost of the answers will be different.