The modernisation plan is ready, the budget provisionally approved. The contractor asks the first question: "Where is the system documentation?". It turns out there is a wiki last updated five years ago, a few diagrams "somewhere on the network drive" and code that serves as its own documentation. The quote goes up by a third. Because the contractor is not pricing the work, they are pricing the uncertainty.
This piece describes a practice that takes that uncertainty off the table: before anyone touches the code of an old application, the knowledge about it gets recovered first. Until recently this stage meant weeks of an analyst's work and few people chose to pay for it. Today AI does most of that analysis in working days. And that changes the order of the whole project.
Map first, code second
Modernising a system without current documentation is like renovating a building without the utility plans. It can be done, but every wall you knock through is a lottery: maybe there is nothing behind it, maybe there is a pipe half the floor depends on. In applications that pipe tends to be an integration with the data warehouse that only the code's author remembered, or a nightly export that accounting quietly relies on.
Which is why the sensible order is the opposite of the intuitive one. You do not start by writing new code, or even with a quote. You start with a map.
What AI extracts from code, database and logs
Modern analysis tools can read three sources of truth about a system: the source code, the database structure and the logs from production use. Crossing them produces a system map that covers four layers.
The first is modules: what the system consists of and what each piece is responsible for, described in language that people outside IT can follow. The second is data flows: where data enters, what happens to it along the way, where it lands. The third is integrations, all the places where the application talks to other systems: accounting, the warehouse, the online store, partners. These are what break most often when things change.
The fourth layer is the least obvious: dead code. Log analysis shows which functions have not been called in years and which tables nobody has written to since 2019. In older systems that ballast is often a sizeable share of the whole. Every line that does not have to be migrated is a real saving in the project.
What the map changes in the "rewrite or modernise" decision
We wrote about that decision separately, in a piece on four criteria: a decision framework. The system map gives those criteria hard data. Without it, technical debt is judged by gut feel and risk by anecdote. With it, everything is in black and white: which modules carry business value, which are dead, where the integrations sit that raise the risk of every change.
The results can surprise in both directions. Sometimes a system that "has to be rewritten from scratch" turns out to be three-quarters healthy and replacing two modules is enough. Sometimes the reverse: an application looks innocent, and the map reveals a dozen or more undocumented connections that make partial modernisation more expensive than a rewrite. Either way, the decision rests on data, not emotions. And a contractor who receives a map instead of a riddle prices the work instead of the risk.
In our view, recovering the map should be a separate, first stage of the modernisation contract, with its own acceptance. Even if after that stage you decide someone else will do the modernisation, or you skip it entirely, the documentation stays in the company and keeps earning its keep.
How to verify what the AI generated
Automatically generated documentation is not an oracle. It has to be checked. The most effective method is simple: a review with the person who knows the system best, often the only such person in the company. The difference from the classic approach lies in that person's role. You are not asking them to write their knowledge down, which nobody enjoys and which drags on for months. You are asking for a review of a finished description, and pointing out "this is right, this is not" goes many times faster than writing from scratch.
A good practice is to walk a few key processes end to end: an order, an invoice, a complaint. If the map correctly describes the critical flows and the spot-checked details, it can be trusted in the remaining areas. That can be done in a day.
What AI will not recover
Here an honest caveat: code says what a system does, but not why. A strange exception in discount calculation may be a bug, or it may be a commercial arrangement from 2016 that still applies to one large client. No code analysis will settle that. Business intent from a decade ago is recovered through interviews: short conversations with people in sales, accounting and operations, held with the map already in hand. The map suggests what to ask; the answers belong to people.
The application's surroundings are a separate topic too: servers, network, backups. We covered documenting that layer in a piece on the infrastructure documentation audit.
At ESKOM AI we run the mapping stage with a team of specialised AI agents supervised by experienced engineers: analysing a typical business system takes working days, and the result is documentation readable for both the board and the technical team. If the decision to modernise follows, further work runs in an automated software delivery process with a full range of tests — unit, integration, E2E, UI, security and performance.
Where to start in your own company
Pick one system: the one whose modernisation you have been postponing the longest, or the one you are most afraid to touch. Commission its map as a standalone, small stage before you ask anyone to quote the rebuild. In a free consultation we will suggest how to plan that stage and what to expect from it.
Book a free consultation via the contact form →