System Design HLD-14.07
Migrating architectures: the strangler fig
Replacing a legacy system piece by piece instead of a big-bang rewrite: a routing facade, incremental cutover and an anti-corruption layer.
The big idea
A ten-year-old system runs the business. It is slow to change and nobody fully understands it, so someone proposes rewriting it from scratch. Big-bang rewrites have a poor track record: the old system keeps changing while the new one is built, the rewrite must reproduce years of undocumented behavior before it can launch, and it delivers no value until the risky day everything switches over.
The strangler fig patternA migration pattern that gradually replaces a legacy system by routing one piece of functionality at a time to new code, until the old system can be retired. replaces the old system gradually. Put a routing layer in front of it. Build one piece of functionality anew, route its traffic to the new code, and leave everything else on the old system. Repeat, piece by piece, until nothing routes to the legacy system and it can be switched off. Each step is small, delivers value, and can be rolled back.
The name comes from strangler fig trees, which grow around a host tree, slowly taking over until the host is gone and the fig stands on its own. Martin Fowler used it to describe this approach to software.
How it works
Step 1: Put a facade in front
- Facade first A routing layer is placed in front of the legacy system. Nothing changes for users: every route still goes to the monolith.
- First slice Search is rebuilt as a new service. The facade routes search traffic there, gradually and reversibly; everything else stays on the monolith.
- Most slices moved Reviews and accounts have moved too. The monolith now only handles checkout, and will be retired once that moves.
The facade can be an API gateway, a reverse proxy or a load balancer with path-based routing ( Reverse proxies (Nginx, Envoy, HAProxy) ). Its job is to decide, per request, which system handles it. Introducing it is the first step and should change nothing for users. From then on, every migrated slice is a routing change.
import zlib
# The routing facade: each path prefix is served by the legacy app or a new service.
# A migrated route can be rolled out to a percentage of users and rolled back instantly.
ROUTES = [ # (prefix, new service, share of users on the new service)
("/search", "search-svc", 100),
("/reviews", "reviews-svc", 25),
]
def route(path, user_id):
for prefix, service, pct in ROUTES:
if path.startswith(prefix):
bucket = zlib.crc32(user_id.encode()) % 100 # stable per user
return service if bucket < pct else "legacy-monolith"
return "legacy-monolith" # everything not yet migrated
for path, user in [("/search?q=lamp", "u1"), ("/reviews/42", "u1"), ("/reviews/42", "u7"),
("/checkout", "u1")]:
print(f"{path:<16} user {user} -> {route(path, user)}")Output
/search?q=lamp user u1 -> search-svc
/reviews/42 user u1 -> reviews-svc
/reviews/42 user u7 -> legacy-monolith
/checkout user u1 -> legacy-monolith Search is fully migrated, reviews are rolled out to a quarter of users (chosen by a stable hash so each user sees consistent behavior), and checkout has not moved yet. Rolling a slice back is a one-line change in the routing table.
Step 2: Choose slices and move data
Pick slices along bounded contexts ( Domain-driven design for architects ), starting with something valuable but low risk, often read-heavy features. Each slice needs its data. Common approaches: have the new service read the legacy database at first, then give it its own store kept in sync through change data capture ( Transactional outbox and change data capture ), then make the new store the source of truth and stream changes back to the legacy system for anything there that still needs them. Verify behavior by running both paths and comparing results (shadow traffic) before switching.
Step 3: Keep the legacy model out
New code must still talk to the old system: reading its data, calling its functions. An anti-corruption layerA translation layer between a new system and a legacy or external one, converting the old model into the new model so legacy concepts do not leak into new code. sits between them and translates. The new service speaks its own clean model; the layer maps it to the legacy tables, codes and quirks. Without it, the new services inherit the old design's problems, and you have rewritten the code without improving it.
Step 4: Finish the job
The pattern only pays off if the old system is actually retired. Track what still routes to it, plan the hardest last slices explicitly, and delete legacy code and data as slices move. A migration that stalls halfway leaves you running and understanding two systems for years.
Trade-offs
| Option | Wins when | Loses when |
|---|---|---|
| Big-bang rewrite | Very small systems with well understood behavior | Huge risk, no value until cutover, chasing a moving target |
| Strangler fig | Large legacy systems that must keep running and changing | Running two systems in parallel for a long time; data sync work |
| Refactor in place (modularize) | Systems whose platform is fine but whose structure is tangled | Does not escape a platform or technology that must go |
Common mistakes
- Attempting a big-bang rewrite of a system that is still evolving.
- Migrating without a routing facade, so every slice needs client changes.
- Letting the legacy data model leak into new services instead of using an anti-corruption layer.
- Starting with the riskiest, most entangled slice.
- Stalling halfway and running both systems indefinitely.
In the wild
The strangler fig pattern, named by Martin Fowler, is the standard approach to modernizing large legacy systems in banks, retailers and governments, often by routing traffic through an API gateway in front of a mainframe or monolith while new services take over endpoint by endpoint. Cloud providers' migration guides describe the same pattern for moving monoliths to services.
Check yourself
-
What is the first step of a strangler fig migration?
Show answer
B. Put a routing facade in front of the legacy system, without changing behavior The facade makes every later slice a routing change.
-
Why roll a migrated slice out to 25 percent of users first?
Show answer
B. To compare behavior on real traffic and roll back easily if something is wrong Gradual, reversible cutovers limit the damage of migration bugs.
-
What does an anti-corruption layer prevent?
Show answer
B. The legacy system's model and quirks leaking into the new services It translates between models so new code stays clean.
-
A migration moved 80 percent of features but the last 20 percent stalled. What is the cost?
Show answer
B. Running, operating and understanding two systems indefinitely The benefit arrives only when the legacy system is retired.
Recap
- Big-bang rewrites are risky; the strangler fig replaces a legacy system one slice at a time.
- A routing facade in front of the old system makes each migration step a reversible routing change.
- Choose slices along bounded contexts and migrate their data with sync or CDC.
- An anti-corruption layer keeps the legacy model out of new code.
- Finish the migration and retire the old system, or you run two systems forever.