Signs You Need to Rebuild vs Refactor Your Codebase
The instinct when a codebase feels bad is often "let's just rebuild it." That instinct is right less often than it feels. Here's how to actually tell the difference.
Signs refactoring is the right call
- The core architecture is fundamentally sound, but specific areas have accumulated debt (inconsistent patterns, missing tests, some tangled modules).
- The product works and has real users, meaning a rebuild risks a feature-parity gap that costs you customers during the transition.
- The team understands the existing codebase reasonably well, even if they don't love it.
- Performance or scaling problems are isolated to specific, identifiable bottlenecks rather than systemic to the whole architecture.
Signs a rebuild is actually justified
- The core data model is fundamentally wrong for what the product has become, not just messy, but structurally unable to represent what the business now needs.
- The technology choice itself is the constraint (an unmaintained framework, a language nobody on the team can hire for) rather than how it was used.
- Nobody on the current team, including the original authors, can confidently explain how significant parts of the system work.
- The cost of continuing to patch the existing system is demonstrably higher than a scoped rebuild, not just a feeling that it "should" be, run the actual numbers.
The middle path most teams miss
A full rebuild and a surface-level refactor aren't the only two options. A strangler-fig approach, building new functionality in a cleaner architecture alongside the legacy system, then incrementally migrating traffic over, often beats both extremes: it avoids the all-or-nothing risk of a full rebuild while still letting you leave the worst parts of the old system behind.
The question that actually settles it
Not "does this code feel bad," but "is the cost of continuing to build on this system, measured in actual missed opportunities and slowed feature velocity, higher than the cost and risk of a rebuild." That's a business question as much as a technical one, and it deserves a real answer instead of a gut call.
See NestJS Backend Development for how a migration or refactor like this typically gets scoped before any code changes.