Incremental Legacy Migration: A Plain-Language Intro for Non-Architects

You have inherited a system that everyone agrees needs to be replaced, but nobody can agree on how to replace it without breaking everything in the process. Your instinct might be to plan a big rewrite — start fresh, do it right this time. That instinct has led a lot of engineering teams into multi-year projects that stall, miss deadlines, or deliver something worse than what they replaced. There is a better approach: incremental legacy migration.

This introduction explains what incremental migration is, why it works, and what the core concepts mean in plain language.

What "Incremental Migration" Actually 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. The existing system contains years of accumulated business logic, edge cases, and quirks. Some of it is documented. Most of it is not. The team only discovers the undocumented parts when the new system breaks in ways the old one never did.

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: The Most 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:

1. 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.
2. You build that piece as a new, independent service.
3. You route traffic to the new service instead of the old one.
4. You verify the new service is working correctly.
5. You remove the old implementation of that piece.
6. 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

The technical patterns are important, but they are not what determines whether an incremental migration succeeds. The most important factors are:

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. Incremental migration feels slow to non-engineers because there is no dramatic launch moment. Setting expectations about how value is delivered throughout the process — not just at the end — avoids pressure to skip steps.

---

If your team is starting down this path and needs experienced guidance — on architecture, sequencing, or execution — reach out to Clixo. We build and migrate production systems and can help you move forward without taking on unnecessary risk.