Strangler Fig: Replace an Old System One Piece at a Time
Learn how a routing layer in front of an old system lets you build new pieces, move users over one piece at a time, and switch the old system off.
In short
The Strangler Fig pattern puts a routing layer in front of an old system so new pieces replace old ones one at a time until the old system can be switched off.
13 min readFree
What You Will Learn
Big software systems are very hard to replace in one go. The Strangler Fig pattern is a way to swap an old system out a small piece at a time, while the old system keeps serving its users. In this lesson you will learn the moving parts, the three-step cycle that repeats for each piece, and the trade-offs you accept. You will also follow an online store that moves one feature at a time.
Some words come up often in this lesson. Read these first.
Key words
- Legacy system
- An existing system that is still in use but is old, hard to change, or built with tools nobody uses any more.
- Monolith
- One large application where many features live together in one codebase.
- Facade
- A single entry point that sits in front of other code, so callers talk to one place and never see the parts behind it.
- Proxy
- A server that receives requests and passes each one on to another server. A facade is often built as a proxy.
- Routing
- Deciding where each request should go, such as to the old code or to the new code.
- Coexistence
- Old and new parts running at the same time, side by side.
- Transitional architecture
- Temporary code and setup that exist only while a migration is in progress.
- Rollback
- Sending traffic back to the old path after a change goes wrong.
- Decommission
- Switch off a system for good and remove it.
- Big-bang rewrite
- Building a full replacement and switching every user to it on one day.
What Is the Core Idea of a Facade in Front of the Old System?
The pattern starts by placing a facade, or proxy, between the client apps and the legacy system. A client is anything that calls the system, such as a web browser or a phone app. The facade intercepts every request. For each one, it chooses either the legacy code or a new service. Clients keep using the same address and the same interface, so they never notice that a migration is going on.
At the start, almost every request still reaches the legacy system. The facade acts like a pass-through. As each new piece becomes ready, the facade starts sending that piece's requests to the new code instead. Over time the old system gets less and less work, and the new system does more.
The clients
The apps and browsers that send requests. They keep calling one address and do not need to know where each feature lives.
The facade
The routing layer. It reads each request and decides which backend should answer it. This is the only new piece that every request must pass through.
The two backends
The legacy system handles everything that has not moved yet. New services handle the pieces that have already been rebuilt.
Fowler, who named the pattern, describes the start in a plain way. You add small new features that sit on top of the old code, but stay separate from it. Then you move bits of behavior out of the old code base, one at a time. The facade is what makes this possible, because it lets the old and new code share one front door.
How Does the Facade Decide Where a Request Goes?
The most common rule is based on the URL path. For example, every request whose path starts with /search can go to the new search service, while all other paths keep going to the legacy system.
The rules live in one place, so changing them changes the traffic. That is why the facade is so useful. A piece can be moved by adding one rule, and moved back by removing it. You do not need to edit the clients or the legacy code to do either.
Tip
Write routing rules so that the default rule sends everything to the legacy system. A new piece then gets a rule only when it is ready, and nothing needs a special case.
What Is the Three-step Cycle?
The work is not one big project. It is a cycle that repeats for each piece of functionality. The cycle has three stages. Each piece moves through them, and when one piece is done, the team picks the next piece and starts again.
- 1
Transform
Build the new version of one piece beside the old system. Pick a piece with clear edges, such as one feature that has its own URLs and its own data. Keep the old code in place while you build.
- 2
Coexist
Run the old and new versions together behind the facade. Start by sending only a small share of the piece's requests to the new version, then a larger share, then all of them. Compare the results as you go. If something looks wrong, send the traffic back.
- 3
Eliminate
When the new piece handles all of its traffic and nothing still calls the old code for it, delete the old code for that piece. The old system is now a little smaller. Then start the cycle again with the next piece.
When every piece has moved, the legacy system has no work left and can be decommissioned. Azure notes that the facade is then usually removed, so clients talk straight to the new system. It can also be kept as an adapter, which is a translator, for older clients that still need the old interface. Either choice is a deliberate step, not something that happens by accident.
Each cycle is small, so each cycle carries less risk and delivers value earlier. The next section explains why small steps matter so much.
Why Do Small Slices Lower the Risk?
A big-bang rewrite puts all of its risk on one day. The new system goes live for everyone at once, so any bug hits every user, and the team may have no quick way back. A strangler migration spreads the risk across many small releases. A bad slice affects only its own route, and the rest of the system keeps working as before.
Rollback is also quick. The old code for a piece still exists until the piece is confirmed, so the team only has to change the routing rule to send traffic back. Fowler points out that replacing a system is hard because the details of its existing behavior are hard to figure out, and much of that behavior is unwanted. The gradual approach lets the team learn those details one piece at a time, with real users.
There is a cost. While the migration runs, two systems must work together, and the routing code and any data sync code are extra work that will later be thrown away. Fowler judges that the lower risk and earlier value outweigh this cost.
Tip
Before you need it, test the rollback switch. Move one small piece to the new system, send it back to the old system on purpose, and check that users see no change.
Worked Example: An Online Store Moves Product Search
Imagine an online store that runs on one legacy monolith. That single application handles the catalog, search, the shopping cart, checkout, and customer accounts. The team wants a new search service with its own search index, which is a structure that finds products quickly by their words. They do not want to touch anything else yet, and the store must stay open during the change.
- 1
Put a reverse proxy in front
A reverse proxy is a server that takes every customer request from the internet and forwards it to a backend. The team points all customer traffic at the proxy. At first, every path still goes to the monolith, so customers notice nothing.
- 2
Build the new search service beside the monolith
The new service gets its own copy of product data, loaded from the catalog. The team tests it with its own requests and checks that its answers match the monolith's answers for the same searches.
- 3
Add one routing rule
The proxy gets one new rule: any request whose path starts with /search goes to the new service. Everything else, including /checkout, /account, and the home page, still goes to the monolith. Only the search requests change owners.
- 4
Coexist and shift traffic
The team sends a small share of search requests to the new service and watches for problems. When results look right, they send a larger share, then all of them. If the new service fails, they remove the rule and customers search through the monolith again.
- 5
Eliminate the old search code, then repeat
Once all search traffic runs on the new service, the team deletes the search code from the monolith. The next piece might be checkout. The team builds a new checkout service, adds a rule for /checkout, and runs the same cycle again.
The program below is a small model of the routing rules. It is not a real proxy. It checks each path against the rules in order, and a path that matches no rule goes to the legacy monolith. The output shows where each request would go.
routes = [
("/search", "new search service"),
("/checkout", "legacy monolith"),
]
DEFAULT = "legacy monolith"
def route(path):
for prefix, target in routes:
if path.startswith(prefix):
return target
return DEFAULT
for path in ["/search?q=lamp", "/checkout", "/account/42", "/"]:
print(path, "->", route(path))
Output
/search?q=lamp -> new search service /checkout -> legacy monolith /account/42 -> legacy monolith / -> legacy monolith
The example also shows a shared-data problem. The new search service needs product data that the monolith also changes. While both systems run, the team must keep the two copies in step, so that a product price changed in the monolith shows the right value in search. The next section covers this problem and others like it.
When Should You Use the Pattern and What Does It Cost?
A good fit
Large systems that cannot be rewritten at once, where the old system must keep running for a long time. It also fits when requests can be intercepted, so a facade can be placed in front of the old code.
A poor fit
Small systems where a full replacement is simple. It is also a poor fit when the requests cannot be intercepted, or when the old system must be shut down quickly.
What you need first
A clear way to split the system into pieces with clean edges. Real legacy systems rarely have such edges, so the team must look for seams, which are places where a piece can be separated from the rest.
What it costs
Two systems running for a while, temporary routing code, and a slower overall finish than a clean rebuild in some cases. The team pays for this in exchange for lower risk and earlier value.
The biggest danger
Leaving the migration half-finished. Temporary routes and sync jobs should be removed once they stop being needed, so each one needs a planned end date.
Pick the migration order with care. Move self-contained pieces with few links to other parts first. Save the parts that touch many others, and the shared records they depend on, for later, when the team has learned how the migration behaves.
Check Your Understanding
Try these two short scenarios. Each one needs the ideas from the lesson to answer.
Quick check
A company has a ten-year-old monolithic booking app. It wants a modern architecture, without downtime and without a risky all-at-once launch. What should it place in front of the app, and what should it move first, and why?
Quick check
A team moved its invoice page to a new service behind a facade. Weeks later, a stale routing rule still sends a few invoice requests to the old code. The team wants to finish the migration. What is the best next step?
Key Takeaways
Put a facade in front
Every request goes through one routing layer, which decides between the old code and the new code. Clients see no change.
Move one slice at a time
Transform a piece, let old and new coexist while traffic shifts, then eliminate the old piece. Repeat until nothing is left in the legacy system.
Finish the job
Plan the shared data, guard the facade, and remove temporary routes and the facade itself once the migration is complete.
Sources
- Strangler Fig pattern, Azure Architecture Center (Microsoft Learn)
- Strangler Fig, Martin Fowler's bliki entry
- Strangler Fig Pattern: How It Works, Examples, and Tools (Catio blog)
- Strangler Fig Pattern: Modernize One Business Capability at a Time (iAastha)
- The strangler fig pattern: modernizing without a big-bang rewrite (Netguru)
Last updated on 18 November 2026
Related lessons
- Design systemsDesign System Examples: How to Read Real Systems as Models
- Design systemsOpen Hours: Drop-In Help Times From Your Design System Team
- System designLatency vs Throughput: Time for One Request vs Work Done Over Time
- System designDomain Name System: How Names Turn Into Addresses in System Design
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.