You Inherited a System Nobody Can Explain. Now What?

Someone leaves. Or you buy a business and inherit its back office. Or a freelancer who built the booking system five years ago just stops answering emails. Either way, you end up with a piece of software running some part of your business and nobody who can tell you how it actually works.

This happens more often than people admit. I've been called in a handful of times to look at systems where the person who wrote them is uncontactable, the code has no comments, there's no spec, and the only "documentation" is a folder of half-finished notes from three years ago. The business still relies on it every day, so it can't just be switched off while someone figures it out.

The instinct is usually to rewrite the whole thing from scratch. I understand why. It feels cleaner than untangling someone else's decisions. But rewriting before you understand what the current system actually does is how you end up quietly breaking things that were working, sometimes for reasons nobody wrote down.

Start with the data, not the code

Code tells you what a system was built to do. The data tells you what it's actually been doing. Before I read a line of an undocumented codebase properly, I want to see the database: the tables, the relationships, and crucially the exceptions.

Look for the records that don't fit the obvious pattern. A customer with a discount code that isn't in any pricing table. An order status that only appears twice in ten thousand rows. A field that's always null except for one client. Each of those is usually a clue to a business rule that got added at some point, probably in response to a real problem, and never got written down anywhere except in that data.

Map behaviour before you map architecture

It's tempting to jump straight into refactoring or redesigning. Resist that until you can answer a simpler question: if I do X in this system, what actually happens? Not what should happen. What does happen.

I do this by running the system in a copy environment and poking at it deliberately. Submit an order with an unusual combination of options. Try to break a validation rule. Watch what gets written to the database and what emails or webhooks fire off in the background. Undocumented systems often have side effects that aren't obvious from the interface, like a nightly job that recalculates something, or an integration that only fires on certain statuses. If you don't find these before you change anything, you find them later, usually when a customer complains.

Talk to the people who use it, not just the people who paid for it

The person who commissioned the system originally often isn't the person who knows its quirks. The staff using it every day usually are. Ask them what workarounds they've developed. "Oh, we never use that button, it does something odd" is exactly the kind of thing that never makes it into a handover document but tells you everything about where the real edge cases live.

Don't confuse "I don't understand it" with "it's badly built"

Some undocumented systems really are a mess. Others are just unfamiliar. A system built by someone with a different background than yours, or a different set of constraints five years ago, can look confusing without being wrong. I try to withhold judgement until I've traced enough of the logic to see whether decisions were considered or accidental. That changes what you do next. A confused-but-sound system can often be documented and gradually improved. A genuinely broken one might need replacing in stages, which is a different conversation and a different budget.

Get ownership sorted before you get technical

Before any of the technical work, it's worth checking something more basic: do you actually have the right to the code, the domain, the hosting accounts, and the data? Inherited systems often come with loose ends here too, an old developer's personal account still holding the keys, a domain registered under someone who's left. Sorting that out isn't exciting work but it protects you if things go wrong later. I've put together a checklist on code and account ownership that's worth running through even for a system you didn't originally commission yourself.

Decide in stages, not all at once

Once you understand what the system does and why, the decision usually isn't a straight choice between "keep it" and "rewrite it". Most of the time it's somewhere in between: keep the parts that work, replace the parts that don't, and integrate it properly with whatever else the business now runs on. That's a slower process than a fresh rebuild, but it's a lot less risky when the thing you're touching is already load-bearing.

I go into this in more detail on my page on modernising legacy software, including how to work out whether a system is worth improving or better retired.

The short version

If you've inherited a system with no documentation, the safest first move isn't a technical one. It's patience. Look at what the data actually contains, watch what the system actually does under real conditions, ask the people who use it daily, and sort out who legally owns what. Only once you've done that does it make sense to start planning what comes next. Rushing that stage is how businesses end up paying twice, once for a rebuild and once to fix what the rebuild missed.