Inheriting a system nobody documented

The system works. It was written by somebody who no longer works with the company, five or seven years ago, and nobody knows how it is built inside. Every time a change is needed, the budget stops at the same sentence: nobody wants to be the one who touches it.

It is one of the most common situations that reaches us, and one of the worst understood. It arrives framed as a technical problem, and in most cases the code is the least serious part. The serious part is that the knowledge of how that system operates lived in one head, and that head left.

This post is what we do when we take over a system like that, in the order we do it. It works the same if you decide to do it with your internal team.

The first thing is not the code, it is the keys

Before opening a single file, we build an inventory of ownership and access. It is the part that causes the most discomfort and the part that most often turns up something broken.

Who holds the domain and who pays the renewal. Where the DNS records live and who can change them. What server or hosting provider it runs on, and whose name that account is in. Where the code repository is, if one exists, and whether you have administrator access. Who holds the database credential. What third party accounts are involved, transactional email, payment gateway, messaging, and which email address created them.

The answer to at least one of those is usually the previous developer's personal email. Not necessarily out of bad faith: accounts were created to solve something quickly and nobody transferred them afterwards. The result is a company operating on infrastructure it does not control, and that is a continuity risk, not an administrative detail.

Regaining control of the keys comes first, always, and sometimes it is the only urgent thing. A system with no documentation but with access in order is a normal project. A system with impeccable documentation whose domain sits in the name of an unreachable third party is an emergency.

The acid test: standing it up from scratch

The technical audit starts with a simple, merciless exercise: try to get the system running in a fresh environment, from the code and the backups that exist, without help from whoever wrote it.

If that takes hours, the system is maintainable even undocumented. If it cannot be done, you have just found the most important problem: that system cannot be rebuilt. It is alive because the server it lives on is still switched on, and the day that server fails, recovery will not be a restore, it will be a reconstruction.

What gets reviewed next, in this order: whether backups exist, whether they are automated, and above all whether one was ever restored to prove it works. A backup that was never restored is an intention, not a backup. Then the data model, which is where the real business logic lives and the most expensive thing to replace. Then the outdated dependencies, to tell what is a security risk from what is merely old, which are not the same thing. And last the code, which by then reads much faster because the data already told you what it does.

An audit like that is bounded in days, not weeks, and delivers something concrete: an inventory, a map of the data model, a list of risks ordered by urgency, and a written startup procedure. With that, the conversation moves from "let us not touch it" to "these are the three things to fix".

Rescue or rewrite

This is the decision everyone wants to make first, and the only one that cannot be made without everything above.

The criterion we use is not the age of the code or the language it is written in. It is the data model. If the data is well structured, with clear relationships and no fields that mean five different things, the system gets rescued: stabilized, documented, and extended with new modules around it. An old system with healthy data is a perfectly good foundation.

If the data model no longer represents how the business operates today, if the same rule is implemented in three places with different results, or if every small change requires touching half the application, then maintaining it costs more than replacing it and the arithmetic gets worse every year.

There is a third path, the one we use most and the one least often offered: replace in parts. The old system keeps operating, the new work is built around the same data model, and modules move over in an order the business decides. There is no big switch day, no operational freeze, and every delivery is already useful. If the replacement involves moving the history, how that is done is in data migration.

If you are in this decision with nobody to test it against, it is exactly the kind of thing that gets sorted out in a thirty minute call.

Stabilize before improving

When we take over an inherited system, the first weeks bring no new features. We discuss this up front, because it can feel like nothing is happening.

Access is moved into the company's name. Backups are automated and one full restore is performed to prove it works. The startup procedure is documented and the environment left reproducible. Dependencies with known security risk are addressed. And the minimum is written down so that another person can get in: how to stand it up, how to deploy, where everything is, what not to touch and why.

It is the least showy part of the work and the part that makes everything else possible. Changing features on a system that cannot be rebuilt is taking a risk that cannot be undone.

When the right answer is to do nothing

There is an honest case against all of the above, and we make it when we see it.

If the system covers what operations need, nobody is asking for changes, and the business has no plans that depend on it, then no project is needed. Three things are needed and none of them is development: recover the access, have an automated and verified backup, and have it written down how to stand it up if the server dies. That is a matter of days.

A stable, boring system that does its job is not technical debt. It is an asset, and modernizing it because it is old is spending for no reason. The conversation changes when the system starts preventing something the business wants to do, not when it turns another year old. In fact, a good share of the cases that arrive asking for a new system do not need software at all, which we cover in when you need better process, not more software.

What to ask whoever takes it on

Four useful questions. What the audit delivers, in what format and in how many days. Whether the first milestone includes moving access into the company's name and verifying a restored backup. How the rescue or rewrite decision gets made, and on what evidence. And what documentation is left at the end, written for whom.

A proposal that jumps straight to "we will rewrite everything" without having opened the system is not evaluating: it is selling what it knows how to do. And one that promises to touch it without auditing it first is taking a risk you will pay for. There are more questions of this kind in twelve questions before hiring an agency.

How we work with this

We take on existing systems, and the first thing we deliver is clarity: an access inventory, the system's real state and risks in order, before proposing a single line of development. If a project comes out of that, it comes out with written scope; if the answer is that none is needed, we say that too. On closing, the code, the data, the access and the documentation are in your name. The full scope is on custom systems.

If you have a system nobody dares to touch, the discovery call runs thirty minutes, it is free and carries no obligation. Leaving it knowing whether your case is a rescue, a replacement or simple administrative housekeeping is already an outcome. You can book it here.