Existing codebases
Taking over an unfinished codebase: what the first week should produce
A practical sequence for inheriting a web application from a previous developer: getting access, getting it running, an honest assessment and a clear next step.
- Published
- Updated
- Reading time
- 3 min
- Layers
- Layers: Logic, Data, Deployment
When a team inherits an application, because a freelancer left, an agency relationship ended or a product was bought, the instinct is to start fixing things. That's usually premature. Until the new team can build, run and deploy the application, every estimate is a guess and every change is a risk.
The first week should produce four things, in order.
1. Complete access, written down
Start by listing every place the application lives. Typical items:
| Area | What to find |
|---|---|
| Code | Repository host, organisation, branches, who has admin |
| Hosting | Provider, account owner, environments (staging, production) |
| Data | Database host, backups, who can restore them |
| Domains | Registrar, DNS provider, TLS certificates |
| Services | Email, payments, analytics, storage, auth providers, API keys |
| Secrets | Where environment variables are stored, and whether they're current |
Two common surprises: accounts registered to a previous developer's personal email, and production secrets that exist only on that developer's machine. Both need resolving before anything else, because they're the difference between owning an application and borrowing it.
2. A working local build
Clone the repository and try to run it from the README alone. Note every step that wasn't documented. This is the most reliable early signal of the project's condition: an application that builds cleanly in an afternoon is in a very different state from one that needs undocumented services, old runtime versions or files that aren't in the repository.
Then do the same for a deployment, ideally to a staging environment. If there's no staging environment, creating one is often the first piece of real work, because it makes everything after it safer.
3. An honest assessment
With a working build, look at the application as a whole rather than file by file:
- Dependencies. How far behind are the framework and major libraries? Are any unmaintained, or carrying known security advisories?
- Structure. Is there a recognisable architecture, or has each feature been added differently?
- Data. Is the schema coherent? Are there migrations, or has the database been edited by hand?
- Tests and checks. What exists, does it run, and does it pass?
- The unfinished work. For each incomplete feature: how far along is it, and is the existing code a foundation or an obstacle?
The output should be written for a decision-maker, not just a developer. "The authentication library is two major versions behind and the upgrade touches every protected page" is useful. "Code quality is poor" isn't.
4. A scoped next step
The assessment should end with options, not a rewrite recommendation by default. Typically:
- Stabilise: update what's risky, add a staging environment and basic monitoring
- Finish: complete the outstanding features on the existing foundation
- Replace selectively: rebuild the parts that can't be salvaged, keep the rest
A full rewrite is occasionally the right answer, but it's expensive and it resets everything the existing system already handles correctly, including the edge cases no one wrote down. It should be a conclusion from the assessment, not an assumption going in.
What to have ready if you're handing this to someone else
If you're about to bring in a new developer or partner, gathering the access list above before the first conversation will save days. So will any history you have: the original brief, a list of known bugs, and the name of anyone who worked on it and might answer a question.
We offer this kind of review as a fixed-price piece of work. See existing codebase support.