Modernising legacy systems: strangler fig and incremental migration

What makes a system legacy

A legacy system is not simply an old one. It is a system that still does something valuable, often something the organisation could not operate without, but that has become hard, risky or expensive to change. Michael Feathers, in Working Effectively with Legacy Code (2004), gave a deliberately provocative definition: legacy code is code without tests, because without tests every change is a gamble. Other common causes are scarce skills (a language or platform few people still know), unsupported technology (an operating system or database past its vendor's end of support), lost knowledge (the people who understood the design have left) and accumulated technical debt in the structure itself, the expensive kind described in Section 1.7.

It is worth saying plainly that most legacy systems are successful systems. They survived because they worked and earned money. That success is also why they are hard to replace: years of real-world use have embedded thousands of small decisions, fixes and business rules that are written down nowhere except in the code and in the habits of the people who use it.

Modernisation therefore needs a reason that can be stated in business terms. Good reasons include: the cost or risk of change is blocking important business goals; the platform is losing vendor support or security patches; skills to maintain it are becoming unavailable; running costs are out of proportion to value; or the system cannot meet new demands for scale, availability or regulation. Weak reasons include fashion, boredom and the belief that new technology is automatically better. Section 11.8 shows how to turn a good reason into a business case.

Why rewrites fail

The obvious response to a painful old system is to start again. In April 2000 Joel Spolsky published an essay, "Things You Should Never Do, Part I", arguing that the decision to rewrite from scratch is among the worst strategic mistakes a software company can make. His example was Netscape, whose browser went nearly three years between major releases while the code was rewritten, during which competitors took the market. His central point was about knowledge: old code looks messy partly because it contains years of bug fixes for situations nobody remembers, and throwing it away throws those fixes away too.

The reasons a big-bang rewrite fails are now well understood. Value arrives only at the end, so the business waits months or years and loses patience. The old system keeps changing while the new one is built, so the target moves and the organisation either freezes the old system (and the business) or pays to make every change twice. Hidden behaviour is missed, because nobody can list every rule the old system enforces. Estimates are optimistic, because the visible features are a fraction of the real work. The data migration and the cutover are left until the end, when they are hardest and riskiest. And the team splits into a prestigious new-system group and a demoralised old-system group. Fred Brooks's second-system effect, from The Mythical Man-Month (1975), adds a further risk: designers replacing a system they know tend to load the new one with every idea the old one could not accommodate.

Large migrations that switch over in one step can also fail very publicly. In April 2018 the UK bank TSB moved its customer data and services to a new IT platform; the platform immediately had serious problems, all its branches and a significant proportion of its 5.2 million customers were affected, and the bank did not return to normal operation until December 2018. In December 2022 the Financial Conduct Authority and the Prudential Regulation Authority fined TSB a total of £48.65 million, finding that it had not adequately planned, organised and controlled the migration or managed the risks from its outsourced supplier.

Practitioners do not all agree that rewrites are always wrong. A rewrite can be the right choice when the system is small, its behaviour is well specified and covered by tests, the platform is truly at a dead end, or the business itself has changed so much that the old behaviour is no longer wanted. Even then, the safest rewrites are delivered incrementally, with the old and new systems running side by side, which is the subject of the rest of this section.

Migration strategies: the Rs

When an organisation reviews a whole portfolio of applications, for example before leaving a data centre, it needs a vocabulary for deciding what to do with each one. Gartner described five such options in the early 2010s. In 2016 Stephen Orban of AWS published six strategies, and AWS later added a seventh, giving the seven Rs now used in its migration guidance. Other cloud providers and consultancies use similar lists with slightly different names. The list is most useful as a reminder that rebuilding is only one option among several, and usually the most expensive.

The strangler fig

Martin Fowler named the most widely used incremental pattern after the strangler figs he saw in the rainforests of Queensland in 2001: vines that germinate in the branches of a host tree, grow down to the ground and gradually surround the host until it dies and the fig stands on its own. He first wrote it up as the strangler application in 2004, later renamed it the strangler fig application and substantially revised the article in 2024. The software version, usually just called the strangler fig, keeps the old system running while new components grow around it and take over its behaviour one piece at a time, until the old system does nothing and can be switched off.

The mechanism has three parts. First, an interception layer is placed in front of the legacy system: a reverse proxy, API gateway or routing facade through which all requests pass. Initially it sends everything to the old system and changes nothing. Second, a slice of behaviour is chosen along a seam (a place where behaviour can be redirected without editing much of the old code, in Feathers' terms), rebuilt as a new component and enabled by changing a routing rule, usually for a small share of traffic first. Third, the process repeats until the legacy system handles nothing, at which point it is retired. Throughout, the routing layer makes each step reversible: if the new component misbehaves, the rule is switched back.

The code that lets old and new coexist (the routing facade, adapters, data synchronisation jobs) is transitional architecture: software built to be thrown away. Teams often resist writing it because it feels wasteful. Fowler's argument, and the experience behind it, is that this cost buys reduced risk and much earlier value, which is almost always a good trade. The real danger is the opposite: a migration that stalls half way, leaving both systems and all the transitional code in production indefinitely. Each slice should therefore remove something from the old system, and progress should be measured by what has been switched off, not only by what has been built.

Ian Cartwright, Rob Horn and James Lewis of Thoughtworks have documented a family of related techniques as Patterns of Legacy Displacement on martinfowler.com (from 2021). They frame the work as four activities that are not a fixed sequence: understand the outcomes you want, break the problem into parts, deliver those parts incrementally, and change the organisation so that the new system does not decay the way the old one did. They also question the instinct to reproduce every feature: much of a legacy system's behaviour may no longer be wanted, and finding out is cheaper than rebuilding it.

Branch by abstraction

The strangler fig works at the edge of a system, where requests can be routed. Some replacements must happen deep inside one codebase: swapping a persistence framework, a pricing engine or a home-grown messaging layer that hundreds of call sites use. Branch by abstraction, a name Paul Hammant introduced while advocating trunk-based development and that Martin Fowler described in 2014, does this without a long-lived version-control branch. The system stays releasable at every step, so the change can be spread over weeks or months while other work continues on the same main line.

Proving equivalence: parallel run and dark launching

The hardest question in any migration is whether the new implementation really behaves like the old one. A parallel run answers it with production evidence: both implementations receive the same inputs, the old one remains authoritative and its answer is returned to the user, and the two results are compared and any differences recorded. GitHub published its Scientist library in 2016 for exactly this purpose, running a control and a candidate side by side and reporting mismatches; similar tools exist for many languages, and the technique is simple to write by hand, as the sketch below shows.

Dark launching, which Fowler describes as calling new back-end behaviour in production without users seeing its effects, is closely related. It is mainly used to test the new path's performance and stability under real load before any user depends on it, while a parallel run concentrates on correctness. Both differ from a canary release, in which a small share of users really do receive the new behaviour.

Both techniques have sharp edges. The candidate must have no externally visible side effects: it must not send a second email, charge a card twice or write to the shared database, so parallel runs are easiest for reads and calculations, and writes need a sandbox or a separate store. Comparisons must ignore legitimate differences such as timestamps, ordering and floating-point formatting, or the mismatch report drowns in noise. And running both paths costs capacity, so the share of traffic sampled is often limited.

def quote_delivery_fee(order):
    old = legacy_pricing.quote(order)          # still authoritative
    try:
        new = new_pricing.quote(order)         # must have no side effects
        if new.amount_pence != old.amount_pence:
            metrics.increment("pricing.mismatch")
            log.info("pricing mismatch", order_id=order.id,
                     old=old.amount_pence, new=new.amount_pence)
        else:
            metrics.increment("pricing.match")
    except Exception:
        metrics.increment("pricing.candidate_error")   # never hurts the user
    return old

Data: the hardest part

Routing requests is relatively easy; moving data and keeping it consistent while two systems share responsibility for it is where most migrations struggle. The first rule is the one from Chapter 7 on data ownership: for every kind of data, at every stage of the migration, the team must be able to say which system is the system of record, which copies exist and how stale each may be. The diagram below shows the typical flip: the legacy system owns the data at first and the new component reads a copy; later the new component owns it and the legacy system receives a copy for the modules that still need it.

Change data capture is the usual way to copy data out of a legacy database without changing the legacy code: a tool such as Debezium reads the database's transaction log and publishes each change as an event, the same mechanism Section 6.7 used to relay an outbox. Event interception, one of the legacy displacement patterns, works at the other end: it catches state-changing requests or messages on their way into the legacy system and forwards copies (or, later, the originals) to the new component. Either way, never let both systems accept writes to the same data independently with two-way synchronisation unless you have no alternative; conflicts are then almost guaranteed.

Legacy data rarely matches the new model. Status codes are integers with undocumented meanings, one table serves three purposes, and dates are stored in local time. An anti-corruption layer, the domain-driven design pattern for protecting a model from a neighbour's, translates between the two so that the legacy system's quirks do not leak into the new code. It belongs to the transitional architecture and should disappear with the legacy system.

The final data migration, moving history and cutting over, deserves its own plan. Profile the legacy data first to find duplicates, orphans and invalid values. Write the mapping explicitly and test it on a full, production-sized copy. Reconcile after every run with row counts, sums of money columns and checksums, not by spot checks. Rehearse the cutover, time it and write down the rollback. Where possible, migrate in cohorts (one region, one customer segment, one product line) rather than everything at once, so that a problem affects a fraction of customers and teaches you something before the next cohort.

Lessons from Kill It with Fire

Marianne Bellotti's Kill It with Fire: Manage Aging Computer Systems (and Future Proof Modern Ones) (No Starch Press, 2021) draws on her experience modernising government and commercial systems, including mainframe estates. Several of its themes are worth carrying into any modernisation.

Modernisation should be justified by the value it delivers and the risk it removes, not by the age of the technology; old technology that is well understood and works may be the least risky part of the estate. Technology choices move in cycles, so a team that replaces a system only because its design is out of fashion is likely to build the next generation's legacy. Incremental improvement of the existing system is usually safer than replacement, and a full rewrite needs an unusually strong justification. Finally, modernisation is an organisational problem as much as a technical one: it needs visible early wins to keep momentum and morale, clear criteria for when it is finished, and attention to the incentives that made the old system decay, or the new one will follow it.