Inherited a messy codebase? How to rescue a stalled software project

It happens more often than anyone admits. The agency stopped answering, the freelancer moved on, or the one developer who understood the system left. You still have a product, customers depending on it, and code nobody on your side can safely change.

This article covers how we take over a stalled software project: what we check first, how we make it safe to work on again, and how to decide between fixing it and rebuilding it. It's the work behind our full-stack development service.

Signs your project is in trouble

You don't need to read code to spot most of these:

• Every release breaks something else, and fixes take longer each time.
• Simple changes get quoted in weeks.
• Nobody can say exactly what's running in production, or how to deploy it.
• You don't control the accounts. The repository, hosting or domain sits in someone else's name.
• There's no documentation and no tests, so knowledge lives in one person's head.
• Pages are slow, or requests time out, and nobody knows why.

One of these is common. Three or more means it's time for a proper review before anything new gets built.

Step 1: secure access and ownership

Before anyone looks at the code, make sure you own it. That means admin access to:

• The source code repositories (GitHub, GitLab or Bitbucket)
• Hosting and cloud accounts (AWS, Vercel, DigitalOcean and so on)
• The domain and DNS
• Databases and backups
• Third-party services: payments, email, SMS, analytics and app store accounts
• Credentials and environment settings, ideally in a password manager or secrets store, not an email thread

If a previous supplier still holds any of these, getting them transferred is the first job. It's much easier while relations are still civil.

Step 2: a code and infrastructure review

Next we review what's actually there and write it up in plain language. The review covers:

• Architecture. How the system fits together, and whether that design can carry where the product is going.
• Code health. Structure, duplication, outdated dependencies and known security issues.
• Tests and releases. What's covered by tests, how changes reach production, and how risky each release is.
• Infrastructure. Hosting, backups, monitoring and running costs.
• Data. Database structure, data quality, and whether personal data is handled properly.

You get a ranked list of risks and quick wins, with an honest view of what it would take to fix each one.

Step 3: stabilise before building anything new

New features on an unstable codebase make things worse. Stabilising usually means:

• Automated checks. Tests around the most important workflows, plus type checks and linting on every change.
• A repeatable release process, so deploying is routine rather than a gamble.
• Monitoring and alerts, so you hear about errors before customers do.
• Fixing the riskiest issues first: security holes, data integrity problems and the bugs that cost you customers.
• Documentation, so the next engineer doesn't start from zero.

The aim is a codebase your team, or any competent team, can change with confidence.

Rewrite or refactor?

Most owners of a troubled codebase want to start again. Usually that's the wrong call. A rewrite throws away years of fixes for edge cases nobody wrote down, and while it's being built the old system still needs looking after.

Refactoring step by step is usually right when:

• The product works, even if it's painful to change.
• The underlying technology is still supported.
• The problems are concentrated in a few areas.

A rebuild deserves a serious look when:

• The platform or framework is no longer supported, or can't be secured.
• The data model doesn't match how the business works any more.
• The cost of each change keeps rising, even after stabilisation.

Even then, we prefer to replace a system piece by piece, so the product keeps running while it improves.

What this looked like on U-Send

U-Send is a dropshipping operations platform with products, orders, payments, disputes and a Shopify integration. A platform with that many moving parts needs exactly the habits above: tests around the order lifecycle, a reliable release process and clear ownership of every account.

FAQ

Should we rewrite from scratch?

Rarely as a first step. Stabilise and review first. Most of the time, refactoring step by step is cheaper and less risky. When a rebuild is justified, the review will show it.

How long does a review take?

Usually two to three weeks as a fixed-price Sprint, depending on the size of the system and how quickly we get access.

What access do you need?

Read access to the repositories, plus access to hosting, the database (or a recent copy) and any documentation that exists. We sign an NDA before we see anything.

Can you work alongside our in-house team?

Yes. We join your stand-ups, work in your repositories and follow your review and release process. See how we work.

---

If you've inherited code you can't safely change, book a scoping call. In 30 minutes a senior engineer will tell you what to secure first, and what a review would cover. You can also read about our full-stack development service.