SyncTrix logoSyncTrix
All articles
Platform11 min read

Wrapping a legacy SOAP system: the facade pattern that buys you a decade

You cannot replace the mainframe this quarter, and you should stop pretending otherwise. A facade lets new work proceed at modern speed while the old system keeps running untouched.

By Lena Voss
Wrapping a legacy SOAP system: the facade pattern that buys you a decade

Every large organisation has a system that works, that nobody wants to touch, and that every new project has to integrate with. The instinct is to replace it. The realistic move, most of the time, is to put a modern interface in front of it so new work stops paying the legacy tax, and to let the replacement question wait until it is actually answerable.

01Why replacement keeps failing

Replacement projects fail for a reason that has nothing to do with technology: the old system's behaviour is not documented anywhere except in the old system. Twenty years of edge cases, regulatory patches and one-off fixes for specific customers are encoded in code that nobody fully understands and everyone depends on.

A rewrite has to reproduce all of it, including the parts nobody knows about, while the original keeps changing. That is why these programmes run for years and are cancelled at seventy percent. A facade sidesteps the problem entirely: the behaviour stays where it is, and you only need to understand the parts you are actually exposing.

Big-bang replacementFacade + strangler
Time to first value12-36 months4-8 weeks
Risk profileOne enormous cutoverIncremental, reversible
Requires full behaviour knowledgeYes, all of itOnly what you expose
Can be pausedNo, sunk cost growsYes, at any point
Typical outcomeOften cancelledShips continuously
Two approaches, honestly compared

02What the facade actually does

It presents a clean REST or event interface to new consumers and translates to whatever the legacy system speaks - SOAP, fixed-width files over SFTP, a database view, a screen-scraped terminal session. New services build against something sane and never learn the old protocol.

It also becomes the place to put the things the legacy system lacks: timeouts, retries, circuit breakers, caching, rate limiting and observability. That is often worth more than the protocol translation, because a legacy system with no timeout handling in front of it is a shared outage waiting for a slow afternoon.

03Resist the urge to improve the model

The strongest temptation is to fix the legacy data model while you are in there - rename the confusing fields, normalise the statuses, drop the columns nobody uses. Resist it in version one. Every transformation you add is behaviour you now own and must debug when the numbers disagree.

Start with a thin, boring translation. Once traffic is flowing and you understand the real usage, introduce a cleaner model as an additive version. The teams that get into trouble are the ones that treat the facade as a rewrite in disguise and reproduce all the risk they were trying to avoid.

PhaseScopeDuration
1. Read-only facadeExpose the highest-traffic reads3-6 weeks
2. Resilience layerTimeouts, breakers, caching, metrics2-4 weeks
3. WritesOne write path, carefully, with reconciliation4-8 weeks
4. StrangleMove individual capabilities behind the facadeOngoing
5. DecideReplace or keep, now with real dataWhen it is answerable
A sequencing that works

04Writes are where it gets serious

Reads through a facade are low risk - worst case you serve something stale. Writes are different, because now two systems can disagree about the truth and the legacy system usually wins by default.

Do writes one path at a time, with reconciliation that compares facade-initiated changes against the legacy system's state and alerts on drift. Add idempotency keys, because the legacy system almost certainly has none and a retry against it is exactly as dangerous as it sounds.

05Then answer the replacement question with evidence

Once everything talks to the facade, replacement stops being a single terrifying decision and becomes a series of small ones. Any capability can be reimplemented behind the same interface and switched over, with the old path still available for rollback.

You will also have something you did not have before: real usage data. Which operations are actually called, at what volume, by whom. A surprising number of replacement programmes shrink dramatically once someone measures that the legacy system's four hundred operations include eleven that anyone still uses.

Topics

legacy system modernizationsoap to rest facadestrangler fig patternmainframe integrationlegacy api wrapper

Lena Voss

Lead Architect · SyncTrix

Writes about the engineering decisions behind production systems - architecture, delivery and the trade-offs that only show up at scale.

Building something like this?

SyncTrix engineers AI, SaaS, platform and cloud systems for enterprises and high-growth teams. Tell us what you're shipping and we'll scope it with you.

Talk to an engineer