Incremental Legacy Migration: A Plain-Language Intro for Non-Architects
A beginner-friendly introduction to incremental legacy migration — what it means, why it works better than rewrites, and the core concepts every team should know.
Incremental legacy migration replaces parts of an existing system while the rest continues to operate. It can let a team test new behavior and retire old components in stages instead of waiting for a complete replacement.
The main decisions are where to draw boundaries, how to route traffic, and when each old component can be removed.
What "Incremental Migration" Means
Incremental migration means you move from your old system to your new system in small, independently shippable steps — not all at once. At every point in the process, the old system is still running and serving real users. You never flip a switch and hope for the best.
Think of it like replacing the floor in a room while people are still walking across it. You work one section at a time. You make sure each section is solid before moving to the next. The room is always usable.
The alternative — replacing everything at once — means the room is entirely unusable until the job is done. If something goes wrong midway through, you have no floor at all.
Why Big Rewrites Fail
A big rewrite has a seductive logic: start clean, design things properly, and the resulting system will be better in every way. In practice, this reasoning runs into several problems:
Hidden complexity. Existing systems contain accumulated business rules and edge cases that may be poorly documented. Review current behavior and compare outputs before replacing a component.
Delayed value. Nothing ships until everything is done. If the project takes 18 months, the business receives no benefit for 18 months. If the project gets cancelled at month 15, nothing ships at all.
Scope creep. A rewrite is an opportunity to fix everything that is wrong with the current system. Teams take it. The scope expands. The timeline extends. The project becomes progressively less likely to complete.
Incremental migration avoids all three problems. Each piece is delivered and ships to production before the next piece begins. The team discovers hidden complexity early, when the scope is small and the stakes are low. Value is delivered throughout the process rather than all at once at the end.
The Strangler Fig Pattern: Common Incremental Approach
The core technique for incremental legacy migration is called the strangler fig pattern, named after a vine that grows around an existing tree and gradually replaces it.
In engineering terms, it works like this:
- You identify a discrete piece of functionality in the old system — something with clear inputs and outputs and limited entanglement with the rest of the system.
- You build that piece as a new, independent service.
- You route traffic to the new service instead of the old one.
- You verify the new service is working correctly.
- You remove the old implementation of that piece.
- You repeat with the next piece.
At the end, the old system has been entirely replaced — but it happened gradually, with each step tested in production before the next step began.
Key Terms You Will Encounter
Facade layer. A component that sits in front of both the old system and the new one and decides where to route each request. Users and other systems talk to the facade and never need to know which backend is handling the request. This is what makes gradual traffic shifting possible.
Service boundary. The line around a piece of functionality that defines what is inside the new service and what is outside. Defining this well is one of the most important and most difficult parts of the migration.
Dual write. During a migration, you often need to write the same data to both the old system and the new one. This keeps them in sync while both are live. Dual write adds complexity but avoids data divergence.
Dark launch (shadow mode). Running the new service alongside the old one, sending it the same requests, but not actually using its responses yet. This lets you compare outputs and catch bugs before real users are affected.
Rollback. The ability to undo a migration step and return to the previous state. A rollback plan should exist for every step of the migration before that step begins.
## What Makes Incremental Migration Succeed
Alongside the technical patterns, plan for:
Discipline about sequencing. One piece at a time. Complete each step — including retiring the old code — before starting the next.
Explicit retirement criteria. Know in advance what "done" means for each piece. Without this, old code paths accumulate and the migration never actually finishes.
Testing at production scale. Staging environments give false confidence. Migration scripts and new services need to be validated against production-representative data.
Stakeholder alignment. Explain what each migration stage delivers and how progress will be measured. Agree on the work needed to retire old paths as well as introduce new ones.