What we found in the codebase and what it was costing them

TL;DR: The gap between how a platform is described and what is actually inside it is one of the most consistent things we encounter when we come into an existing codebase. This post walks through what the first five days of a structured technical assessment actually involves, what we found when we came into a large-scale live platform and the pattern that keeps appearing across every codebase we have assessed.

The access request comes through on a Monday morning. Repo permissions, staging environment credentials, a brief from the founder explaining what the platform does and what they need built next.

By Wednesday afternoon, the picture looks different from the brief. This is not unusual. It is one of the most consistent things we encounter when coming into an existing codebase, and it is almost never because the founder has been unclear. The people closest to a system stop seeing it clearly after a while. The workarounds become invisible. The decisions that made sense in year one become load-bearing walls that nobody questions in year three.

The first week is always archaeology before it is engineering.

What the five-day assessment actually involves

Before we write a line of code on any existing codebase, we run a structured five-day technical assessment. This is not optional and not a formality. It is the only moment in an engagement where changing direction is still cheap.

Days one and two: codebase structure and architecture

We are looking at how the application is organised, what the dependency tree looks like and where the business logic lives. Is it cleanly separated from the presentation layer or tangled through it? What test coverage exists? Which version of the framework is the application running on, and is that version still supported?

We are also looking for the things that do not show up in a brief. A helper function that half the application depends on but that nobody has touched in four years because everyone is cautious about what happens if they do. A database query running on every page load that made no difference when there were two hundred users and slows everything down now there are twenty thousand.

Day three: infrastructure and deployment

How does code get from a developer's machine to production? Is there a CI/CD pipeline? If there is, does it run automated tests before deployment or does it just move code? Is the deployment process documented, or does it exist primarily in one engineer's head?

This is where we find what we call the single-point-of-failure engineer. The person whose laptop has the deployment script. The one who needs to be online when anything goes to production. Sometimes there are two of them. Occasionally there is just one, and they have been on holiday twice in the last year, and both times a release was delayed until they got back.

Day four: data and integrations

What does the database schema look like? Are there tables that reflect how the business worked in year one rather than how it works now, with columns that are no longer used and relationships that no longer make sense? Are there third-party integrations the application depends on, such as payment providers, communication APIs and analytics tools, where the integration is running on a deprecated API version with no upgrade path documented?

Day five: documentation and knowledge

What exists in writing and what exists only in people's heads? This is usually the most revealing day. A codebase with good documentation is one where the team has been thinking about continuity. A codebase where the documentation was last updated eighteen months ago is one where the team has been heads-down building and hoping nobody leaves.

What we found in a platform we know well

When we first came into the Pitchero codebase, the platform was already serving millions of users across thousands of grassroots sports clubs. PHP and Ruby on Rails. Live every weekend with real events, real payments and real people depending on it.

The assessment revealed the kind of complexity that only accumulates over years of genuine growth. A large-scale platform built by multiple engineering teams over time, with architectural decisions that made complete sense when they were made and had compounded into constraints by the time we arrived. The deployment process worked but required specific knowledge to run safely. Test coverage existed in some areas and was absent in others, which meant that certain parts of the codebase could only be changed carefully and slowly.

None of this was a failure of the teams that built it. It was the natural result of a platform that had been built to move fast and had moved fast. The challenge was not fixing what was broken. The challenge was understanding what was load-bearing before we touched anything.

That understanding is what the five-day assessment produces. Not a list of problems. A map of the system as it actually is, which is always different from the system as it is described.

The work since then, which includes continuous development support, feature delivery across web and mobile and backend stability across a platform now serving over five million users, has been built on that foundation. You can read more about the Pitchero engagement in our case study.

The pattern that keeps appearing

Across every codebase we have assessed, the specific problems are always different. The underlying pattern is almost always the same.

A team builds something quickly because they need to move quickly. The shortcuts taken in that phase are not mistakes. They are reasonable trade-offs given what the team knew and what the business needed at the time. Then the platform grows. The team grows. New engineers join who did not build the original system and have to infer its logic from the code itself. The shortcuts that were temporary become permanent because changing them requires understanding them first and nobody has made time to do that.

The assessment is not there to judge those decisions. It is there to make them visible before a new team starts building on top of them.

The businesses that get the most out of bringing in an external development partner are the ones that give that assessment the time it needs. Two weeks of structured discovery before a single feature is built almost always produces a faster and less disruptive engagement than starting to build immediately and discovering the constraints mid-project. It is a pattern we see consistently enough to have built it into every engagement we take on.

Frequently asked questions

What does a codebase assessment involve for a UK startup? A structured technical assessment typically runs five to ten working days and covers codebase structure and architecture, infrastructure and deployment process, data and third-party integrations and documentation. The output is a documented picture of the current state, including what is working well, what is creating friction and what carries the most risk before any new development begins.

Why does a development partner need two weeks before starting work? The first two weeks are the only point in an engagement where changing direction is still cheap. Architectural decisions made in week one affect everything built afterwards. A team that understands the existing system before they start building makes fewer expensive corrections than one that discovers constraints mid-build.

What is technical debt and how does it affect a startup codebase? Technical debt is the accumulated cost of shortcuts taken during earlier development. It is not inherently a problem. Most fast-moving startups carry it. It compounds over time as documentation degrades, knowledge leaves the team, and the original decisions become harder to change without understanding them fully. A codebase assessment makes technical debt visible and helps prioritise which parts to address first.

What should a CTO look for when onboarding a new development partner into an existing codebase? The most important signal is whether the incoming team insists on a structured assessment before building. A team that wants to start immediately without understanding the existing system is either overconfident or under-resourced. A team that asks for two weeks to assess before committing to a scope has done this before and knows what it does not know yet.

How Aecor helps

Every engagement we take on with an existing codebase starts with a structured assessment. We have run this process across platforms of all sizes, from early-stage SaaS products to large-scale consumer platforms like Pitchero. The structure of the assessment is consistent. What it reveals is always different.

If you are considering bringing in an external development partner and want to understand what a well-structured first engagement looks like, a free 60-minute technical discovery call is a good place to start. We will walk through your current platform, what an assessment would involve and what the first few weeks of a well-run engagement typically look like. 

Book your free Technical Discovery Call