Facing an old, hard-to-maintain legacy codebase, the instinct is often to propose starting over. That's usually the wrong call for a system actively running a business. This guide explains why, and the more reliable way to migrate it.
In this article
Key takeaways
- A full rewrite means running two systems in parallel for months or years while the new one catches up.
- The strangler fig pattern migrates route by route or feature by feature, so the business never bets everything on one cutover date.
- The hardest part is understanding what the old system actually does, including undocumented edge cases.
- A full rewrite is occasionally the right call, but only when the old architecture is fundamentally incompatible with what the product needs to become.
The instinct to rewrite, and why it's risky
The instinct when facing an old, hard-to-maintain codebase is often to propose starting over: a clean rewrite, modern stack, none of the accumulated compromises. It's an understandable instinct, and it's usually the wrong call for a system that's actively running a business.
A full rewrite means running two systems in parallel for months or years, while the new one slowly catches up to everything the old one already does, quietly and often undocumented.
The strangler fig pattern
The strangler fig pattern is the more reliable alternative. New functionality gets built in the new system, and traffic gets routed to it incrementally, route by route or feature by feature, while the old system keeps running everything that hasn't been migrated yet.
The old system shrinks over time instead of getting replaced all at once, and at no point are you betting everything on a single cutover date.
The hardest part: understanding what the old system does
The hardest part of this approach isn't writing the new code. It's understanding what the old system actually does, including the parts nobody remembers deciding on purpose.
A surprising amount of legacy behavior exists because of a specific edge case from years ago, not because of a documented requirement. Migrating without preserving that behavior recreates a bug the original system quietly fixed a long time ago.
Start by instrumenting the old system
A practical first step is instrumenting the old system before touching it: logging which routes and features actually get used, and how often.
Legacy systems accumulate dead code the same way they accumulate everything else. Migrating unused functionality is wasted effort that a full rewrite would have wasted too, just less visibly.
When a full rewrite is the right call
A full rewrite is occasionally the right call, usually when the old system's core architecture is fundamentally incompatible with what the product needs to become, not just outdated in its tooling. That's a real but less common case.
For most legacy modernization work, incremental migration gets you to a maintainable system faster, with far less risk to the business running on it in the meantime.
Common mistakes
- Betting everything on a single cutover date. The strangler fig pattern avoids this by migrating incrementally.
- Skipping instrumentation before migrating. Without it, you risk migrating dead code nobody uses.
- Assuming undocumented behavior doesn't matter. It's often a quietly-fixed edge case from years ago, not an oversight.
FAQ
Is a full rewrite ever the right call?
Occasionally, when the old system's core architecture is fundamentally incompatible with what the product needs to become, not just outdated in its tooling.
What's the strangler fig pattern?
An incremental migration approach where new functionality is built in the new system and traffic is routed to it feature by feature, while the old system keeps running everything not yet migrated.
The bottom line
A full rewrite sounds clean, but it's the riskiest way to modernize a system still running a real business. The strangler fig pattern gets you to a maintainable system with far less risk. The same care about not breaking what depends on the old thing applies to retiring a single feature, just at a smaller scale.
Working with a system nobody wants to touch? Talk to our team.
