Moving off a system nobody documented

The hardest migrations are not the ones with the most data. They are the ones where the rules only exist inside a program nobody has the source for.

A business that has been trading for twenty years is usually running software that has been there for most of them. It works. It also has no documentation, the developer is long gone, and a handful of behaviours nobody can explain have quietly become part of how the company operates. Replacing it is not really a software project; it is an archaeology project with a deadline.

The instinct is to gather requirements from the people who use it. That is necessary but not sufficient, because the things that break a migration are rarely the things anyone thinks to mention. Nobody says "and the discount is calculated before tax on this document type but after tax on that one", because nobody knows. They just know the totals come out right today.

So the reliable method is to treat the existing system as the specification and prove the new one matches it. Take the real data, run both, and compare the outputs document by document until they agree. Where they disagree, the old system is right until proven otherwise — and quite often the investigation turns up a rule worth keeping that nobody had ever written down.

The same discipline applies to the data itself. Legacy databases accumulate assumptions: a field that means one thing in records before a certain year and another after, a status code used for two purposes, numbers stored as text so they sort in an order nobody intended. These are not defects to be cleaned up on the way through, at least not initially. They are facts about the business's history, and a migration that silently "fixes" them changes historical figures that somebody once signed off.

The practical consequence is that a good migration runs the old and new systems side by side for a period, on the same real data, with the numbers reconciled between them. It is slower than a weekend cutover and considerably less exciting. It is also the difference between a go-live and an incident.

This is the work behind Nuga. It did not start as a blank page; it started as a legacy distribution system that a real business depended on, and every rule in it had to be understood before it could be rebuilt.