Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Strangler Fig

Replace a legacy system one capability at a time behind a facade that sends each request to the old or the new code: where to cut first, who owns the data while both systems run, proving a slice before the flip, and the migration that stalls halfway.

A release that changed nothing

The first thing a university's IT team shipped, in its plan to replace the student records system, was a release that changed nothing for anyone. The old system is one application from 2006 behind the student portal, the registry staff's screens and the admissions import. It enrols students, records grades and issues transcripts, and it cannot pause for a semester while something new is built.

A rewrite with one switch-over weekend would mean years building a system that serves nobody, against a target that moves because the old one keeps getting features, then one cutover where anything wrong is wrong for every student. The team chose the opposite: put a layer in front of the old system that decides, request by request, whether old or new code answers, and move one piece at a time until nothing is left behind it. Martin Fowler named this the Strangler Fig, after a plant that grows around a host tree until it stands in the tree's place. Whether the new side is many services or one new application is a separate choice, the one Microservices vs monolith weighs.

The front door comes first

That release was the layer in front, the facade: a reverse proxy with a routing table, this path to the new code, everything else to the legacy app. Shipped with every route pointing at the legacy app, it showed under real traffic whether the facade added latency or errors before anything new depended on it. The routing itself is ordinary Gateway Routing.

Keep the facade dumb: each rule a path, a method, at most a header, mapped to old or new. A business rule that creeps into it ("postgraduates in the law school go to the new grades service unless…") turns it into a third system to maintain and, one day, to migrate. And flip one capability at a time: moving many at once brings back the all-or-nothing cutover the pattern exists to avoid. The facade also sees only what passes through it; a job inside the legacy app or a report reading its database directly is not a request it can redirect.

Choosing the first slice

A slice is a capability the new side takes over, with every route that serves it. The team began with the transcript, the PDF a student downloads for a job or a graduate application, served by GET /students/{id}/transcript. It is read-only, so a wrong answer is fixed by flipping the route back, with no data to repair, though a wrong PDF a student already downloaded may need reissuing. It is requested often enough to show problems within days and small enough to build in weeks, yet it still puts a new service, its pipeline and monitoring, and a facade rule into production. The new service reads the grades it prints from the legacy app and owns nothing yet.

A good seam is a boundary the data respects. A capability whose rules touch twenty tables that other capabilities also write is not a seam yet, however tidy its URL looks.

Who owns the address while both systems run

The second slice, contact details, was the first that writes. The new Student service took over PUT /students/{id}/address and stored addresses in its own database. A week later the registry's enrolment letters started going to old addresses: the staff screens that print them still ran on the legacy app and read its address table, and nothing had told that table about the changes the new service had accepted.

The rule it taught: at any moment each piece of data has one owner, the only system that accepts changes to it, and every other copy follows it. Once the Student service owns addresses, the legacy app keeps a copy for whatever there still reads it, and each change is sent back to it. The models rarely match (one address object on the new side, four columns and a two-letter country code on the old), so the translation sits in a layer that keeps the legacy model out of the new code, the Anti-Corruption Layer.

One slice moved, its data sent back

Address changes reach the new Student service, which owns the address and sends each change back to the legacy app through a translating layer, so the legacy screens print current addresses once each change has arrived.

A handler that writes its own database and then calls the legacy app makes two independent writes, and a crash between them leaves the copies disagreeing with nothing to retry. Send the change from a durable record of it instead: an outbox row written in the same transaction as the address (Transactional Outbox), or the database's change log (Change data capture).

Ownership also decides whether a flip can be undone. Moving the address route back to the legacy app is only a routing change once the legacy app has every address the new service accepted: pause address changes, let the sync-back drain, then flip, or a change still in transit is lost or overwrites a newer edit. So keep legacy authoritative, or sync the new writes back to it, until the route proves itself. Every writer of the field moves together, too: the portal, the registry screens and the admissions import all set addresses, and if one still writes the legacy table, two systems accept changes to one field and the copies quietly contradict each other. The Monolith to Microservices Challenge asks for both: data kept in sync during the transition, and no new service reaching into the monolith's database.

Proving a slice before the flip

For the transcript, the facade sent each request to both sides for two weeks, returned the legacy PDF, and compared the grades the two printed; each difference was a bug in the new service or the old one, unless a grade had changed between the two reads. Running both and using only the old answer is Parallel Run, with its own rules for what to compare and how to keep the shadow side from writing.

Writes are harder to run twice, so the address route moved by share: the facade sent 5% of students' address changes to the new service, then 25%, then all, watching errors at each step. The share was chosen by student id, not by request, and applied to all three writers, so each student's address still had exactly one owner. Shifting traffic in steps and stopping on bad metrics comes from Canary Deployment.

Stuck at seventy percent

A slice is finished when the legacy code behind it is deleted, not when the new code goes live: once the facade's logs show the route no longer reaches the legacy app, and every direct reader of its tables and every caller of that code inside the legacy app has moved, the legacy code and the sync-back go, and the facade rule becomes plain routing to the new side. Three years in, the university's facade sent 70% of requests to new services, and little legacy code had been deleted. The grading and progression rules, the hardest part, were untouched, and the sync-backs, the facade and two on-call rotations had become permanent. A half-finished strangler usually costs more than either system alone, and it is a common way for these migrations to end.

Two habits help. Count progress by what was switched off (legacy routes, tables and jobs deleted) rather than by what was built, because the new side can grow for years while the old one stays the same size. And schedule the hardest capability while the team and the budget are still there, not last. Sometimes the right call is to stop and keep the core in the legacy app: two systems behind a facade is a defensible end state when it is chosen and priced, not left behind.

Flipping capabilities on a Grid

The Strangler Fig Challenge asks for this structure in at most eight nodes, the translation layer that protects the new services from the legacy model included. Label each facade edge with the capability it carries and draw the sync-back through the Anti-Corruption Layer, so that a reviewer can pick any migrated capability and see that the legacy system would still have its data if that edge flipped back.

Practice this