Migration Path: From a Legacy Stack to a Modern One

Migration Overview already names the strangler fig as the default strategy for every migration in this section; for a legacy stack specifically, the strangler’s routing seam is a reverse proxy or gateway placed directly in front of the legacy application. Every request Bookshop receives arrives at that proxy first, which decides — by path, by an HTTP header, or by which cohort of users a request belongs to — whether it is served by the still-standing bookshop-web.war or by the new bookshop Spring Boot application growing up around it. API Gateway and Backends for Frontends already covers the gateway itself in depth; this is that same seam, used specifically as the legacy migration’s strangler routing point.

Three products implement this proxy in practice: YARP for a .NET-hosted proxy, NGINX as a general-purpose reverse proxy, and Spring Cloud Gateway when the proxy itself is worth writing as a Spring Boot application with programmable routing logic. All three can route by path (/catalogue/** to the new service, everything else to the legacy WAR), by a header the client or an upstream load balancer sets, or by cohort — a percentage of users, or a specific beta group, routed to the new path while the rest keep hitting the legacy application, so a regression affects a bounded, known slice of traffic rather than everyone at once.

Richardson’s second legacy-displacement strategy (Microservices Patterns ch. 13.2.2) is often the single highest-leverage first move available: before extracting any business capability at all, expose the existing business logic as an API, and rebuild only the UI on top of it as a SPA. For Bookshop, that means giving `bookshop-web.war’s Struts actions a REST facade — often a thin wrapper around logic that does not move yet — and replacing the JSP/jQuery pages with a React (or Angular, or Vue) SPA that consumes that facade instead of receiving server-rendered HTML.

This split is worth calling out explicitly because it is the exact seam Migration Path: From a Monolith to Microservices reuses later: once Bookshop’s UI talks to its backend only through an API, extracting any one capability behind that API into its own service changes nothing the UI depends on. Doing the presentation split first means the harder, capability-by-capability extraction work that follows never has to touch the UI again.

Two techniques from Fowler and ThoughtWorks’s legacy-displacement catalogue apply once a piece of legacy logic is being replaced in place rather than routed around:

While the legacy Oracle schema and the new PostgreSQL-backed domain model coexist, code on the new side that needs to read or write legacy data needs to do so without importing the legacy model’s own shape — its table-per-column naming, its stored-procedure return codes, its lack of any real aggregate boundary — into the new domain. Richardson’s anti-corruption layer (Microservices Patterns ch. 13.3.1) is exactly this translation boundary: a dedicated adapter that speaks the legacy system’s protocol and data shapes on one side, and the new domain model’s own types on the other, so nothing in bookshop’s new domain layer ever has to know what the legacy Oracle schema actually looks like. For Bookshop, the anti-corruption layer sits between the new `bookshop application and the legacy Oracle schema’s supplier-catalogue tables and stored procedures for as long as both are in use, translating rows and procedure calls into Book and Price domain objects the new code already understands.

For as long as both the legacy Oracle schema and the new PostgreSQL database hold overlapping data — book catalogue rows during the strangler period, say — the two need to stay consistent with each other, and there are two structurally different ways to do it:

CDC is the safer default whenever the legacy system’s log-based change stream is available and the legacy application’s own code cannot be touched; dual writes are acceptable only for low-stakes, easily-reconcilable data where an occasional divergence is cheap to detect and fix.

Not every piece of a legacy stack needs strangling. Where the current framework is itself still evolving with a credible backward-compatibility story — Spring’s own major-version upgrades are the concrete example, each one documented with a migration guide precisely because the framework’s maintainers invest in not breaking existing applications outright — incrementally upgrading in place (Spring 3 XML configuration to Spring Boot autoconfiguration, one module at a time, without ever removing the deployable) can reach the modern target faster and with less risk than building a parallel strangler application around it. Strangling is the right tool when the current stack is no longer evolving at all (Struts 1 has had no meaningful new release in years; see What’s Changed & Migration) or when the gap between current and target is too large for an in-place upgrade path to exist.

Whichever technique moves a given piece of functionality, the actual moment of cut-over is controlled by a feature flag: a runtime switch that decides, per request or per user cohort, whether the legacy or the new implementation handles it. This is the same mechanism the strangler proxy’s cohort-based routing uses at the HTTP layer, applied one level lower — inside a single request that has already reached the new bookshop application, a flag can still choose between an old and a new code path for one specific piece of logic, independent of routing. Rolling the flag from "legacy for everyone" to "new for a 5% cohort" to "new for everyone" gives every cut-over a bounded blast radius and an instant rollback (flip the flag back) if something goes wrong.

A legacy strangler migration ends only when there is nothing left the legacy system does that the new stack does not already do at least as well — and that has to be an explicit, checked list, not a feeling. Concretely, for Bookshop’s bookshop-web.war, decommissioning is safe once:

Only once every item on that list is checked does turning off WebLogic and dropping the legacy schema stop being a risk and start being simple cleanup.