Retrofitting AI into a legacy system

Meet "Continental Insurance" — a representative composite. Its claims platform is 20 years old: a monolith on an older stack, a database that is the undisputed system of record, batch jobs no one wants to touch, and a business that processes thousands of claims a day on top of it. Leadership wants AI to triage incoming claims and draft adjuster summaries. What they cannot have is a rewrite, a multi-quarter freeze, or any risk to the system of record. This is the most common enterprise AI job that isn't a greenfield demo, and it is dominated by three forces a new project never feels: you must not break what works, you must not couple to legacy internals, and you must be able to roll back in seconds.

1 · Framing the retrofit — the constraints that rule out a rewrite

Picture the meeting you've probably sat in. A VP has seen an AI demo, it triaged a claim beautifully, and now the ask lands on your desk: "Put this into the claims platform." You open the codebase — a 20-year-old monolith, a database ten teams read from, batch jobs whose authors left the company a decade ago — and the demo's confidence evaporates. The temptation is to say the honest-sounding thing: "This is too tangled; let's rebuild the claims flow cleanly and put AI in the new version." That sentence is how enterprises spend two years, burn a budget, and ship nothing while the old system keeps running anyway.

Here's the reframe that separates people who succeed at retrofits from people who stall. A retrofit is not a software problem first — it's a constraints problem. Before you draw a single box, you write down what you are not allowed to break, and those forbidden things do most of the design work for you. Think of it like renovating a house you still have to live in: you can't demolish the load-bearing wall, you can't shut off the water for a month, and every change has to be reversible if it leaks. Those aren't annoyances that get in the way of the design — they are the design. You don't get to pour a new foundation; you get to add a room the old house can support.

The formal version: a legacy retrofit is bounded by three hard limits a greenfield project never feels. You must not break what works — the claims platform processes real money every day, so the legacy path has to keep running untouched. You must not couple to legacy internals — the moment your AI code imports the legacy schema's quirks, that schema can never change, and you've made the old system more brittle by "improving" it. And you must be able to roll back in seconds — not after a deploy, not after a hotfix, but instantly, because the business cannot wait for your incident review. The common mistake is treating these as obstacles to route around; the skilled move is to treat them as the specification. Read them carefully and they name their own solutions: "keep the legacy path live" is a feature flag, "don't couple" is a translation boundary, "roll back instantly" is a kill switch. The table below turns each business constraint into the engineering consequence it forces — and by the end of the section the architecture has essentially written itself.

The instinct is "let's just rebuild the claims flow with AI in it." In a real enterprise that is how you spend two years and ship nothing. Start by writing the constraints that make a rewrite a non-starter, because they also point straight at the pattern you should use instead.

2 · Integration patterns — how the AI touches the legacy system

Every retrofit that goes wrong goes wrong at the seam. Not in the AI, not in the model — at the exact point where the new code reaches into the old system. Someone, under deadline, calls the legacy database directly, references a column named clm_stat_cd, learns that NULL in that column secretly means "pending," and hard-codes that quirk into the AI path. It works on Tuesday. Six months later the legacy team wants to rename that column, discovers the AI now depends on it, and freezes — the "improvement" has made the old system less changeable than before you touched it. That is the failure this section exists to prevent, and it's almost always caused by how the AI connected, not what the AI did.

The mental model to hold is a power adapter for foreign travel. You don't rewire the hotel's electrical system to charge your laptop, and you don't rewire your laptop to accept the hotel's socket — you put a small, dumb adapter between them that translates one shape into the other. Neither side has to know or care about the other's internals; either can be replaced without touching the other, as long as the adapter keeps translating. In a retrofit that adapter is the anti-corruption layer (ACL): a translation boundary where the legacy system speaks its 20-year-old dialect on one side and the AI speaks a clean, modern domain model on the other. The name is deliberate — its whole job is to stop the legacy schema's "corruption" (its quirks, its cryptic enums, its nulls-as-flags) from leaking into and infecting your new code.

Precisely: the ACL is the boundary; the other three patterns are the specific mechanisms you place inside it depending on how the legacy system lets you connect. An adapter/façade wraps a callable surface the legacy already exposes (an API, a stored procedure) behind a clean interface. An event tap (change-data-capture) reads the legacy database's change log as a stream, so you get current data without ever touching its write path. A sidecar/strangler façade is a new service that sits in front and routes some requests to the AI and the rest to legacy. The common mistake is to reach for one pattern and think you're done; in practice you combine them — an event tap for reading, a façade for intercepting, both wrapped in an ACL so neither welds to the legacy schema. The table lays out when each earns its place.

The core decision is how the new AI capability connects to the old system without becoming welded to it. Four patterns cover almost every case; you usually combine them. The unifying idea is an anti-corruption layer (ACL): a translation boundary so the AI speaks a clean domain model and never learns the legacy schema's 20 years of quirks.

3 · The strangler-fig architecture

The pattern is named after a tree, and the tree is worth picturing before the architecture. A strangler fig starts as a tiny seed dropped in the canopy of an existing host tree. It sends roots down along the trunk, slowly, over years — and the host keeps growing, keeps bearing fruit, keeps doing its job the entire time. Only gradually, branch by branch, does the fig take over the work the host used to do, until one day the fig stands on its own and the host is gone. At no point was the forest without a working tree. That is exactly the migration guarantee you want on a live claims platform: at no point is the business without a working system.

Contrast this with the alternative every executive secretly wants — the big-bang cutover, where you build the new thing in parallel and flip everyone over on a Saturday night. Big-bang has one property that makes it seductive (it's conceptually simple) and one property that makes it catastrophic (its blast radius is everything, at once). If the new system has a bug, every claim is affected, there's no old path to fall back to because you just decommissioned it, and your rollback is a weekend of restoring backups while the business is down. The strangler-fig trades that terror for patience: you route one thin slice of traffic through the new AI path, keep the legacy path fully authoritative for everything else, and grow the slice only as it earns trust. Your blast radius at any moment is just the slice you've enabled — and you can always shrink it back to zero.

The mechanism that makes this possible is a façade: a single entry point that sits in front of the legacy system and, per request, decides "does this one go through the AI path, or straight to legacy?" The critical detail — the one beginners get wrong — is the direction of the default. The façade does not replace the legacy system; it fronts it, and legacy remains the fallback for every request the flag hasn't enabled or the AI can't handle. New capability is always an addition you can switch off, never a bridge you've burned. Read the diagram below as one claim's journey through that façade: it arrives, the façade checks whether this slice is AI-enabled, and if so the AI path reads legacy data through the ACL and emits an advisory output — while the legacy system stays the system of record the whole way through.

The strangler-fig pattern (a well-known, publicly documented approach to legacy modernization) is the backbone: put a façade in front of the legacy system, route a slice of traffic through the new AI path, and grow that slice only as it earns trust — while the legacy path stays authoritative the entire time. Read the diagram as one claim's journey: it enters the façade, which decides whether this slice is AI-enabled; the AI path reads legacy data through the ACL, produces an advisory output, and the legacy system remains the system of record.

4 · Data plumbing — reading legacy data safely

Here is the tension that quietly sinks retrofits. The AI is only useful if it sees current claim data — a stale view means it triages against last week's state and gives confidently wrong answers. But the write path to that data is precisely the thing you swore in §1 you would not touch. So you're caught: you need fresh data, and the obvious way to get fresh data (query the live database, or worse, write your enrichments back into it) is exactly the move that couples you to the legacy schema and risks corrupting the system of record. Every instinct pulls toward "just read the claims table directly," and every one of those instincts is a trap.

The resolution is a single discipline, and it's worth saying as a slogan you can carry into any retrofit: read, never reach in. Think of the legacy database as a river you're not allowed to dam or divert — but you're allowed to stand on the bank and watch what flows past. That watching is change-data-capture (CDC): instead of querying the database, you tap its change log — the same log the database already writes for its own replication and recovery — and turn every insert and update into an event. You've added zero code to the legacy write path; you're just observing changes it was already recording. Those events flow through the ACL (so they arrive as clean domain objects, not raw legacy rows), into a separate read model — a store shaped for exactly the queries the AI needs. The AI reads only from there, so it's decoupled from both the legacy schema and the legacy database's load.

Two consequences follow, and both catch people out. First, this read model is eventually consistent: there's a small lag between a change hitting the legacy DB and appearing in the read model. That's usually fine — but it means you must monitor freshness and degrade gracefully (fall back to legacy for a request) if the lag grows too large, rather than silently acting on stale state. Second, and non-negotiable: the AI's own outputs never flow back into the system of record directly. They land in an advisory queue, where a human or the legacy system validates them before they become truth. The distinction that matters is this — eventual consistency on the read side is acceptable; a corrupted system of record is not recoverable trust. Lose data integrity once and you lose the project, because no one will believe the AI's outputs again. The numbered flow below traces a change from the legacy DB all the way to a safely-quarantined advisory output.

The AI needs current claims data, but the write path to the system of record is exactly what you promised not to touch. The answer is to read, never reach in: capture changes as a stream and build a purpose-shaped read model the AI queries, translated through the ACL. The legacy DB stays authoritative and untouched; the AI works off a derived, eventually-consistent view.

The read-side data flow

1. Change-data-capture (CDC) taps the legacy DB's change log and emits events — no code changes to legacy writes.
2. An ACL transform maps legacy rows into a clean domain event (stable names, resolved enums, no nulls-as-flags).
3. A read model (a separate store shaped for the AI's queries) is built from those events.
4. The AI path queries the read model, never the legacy DB directly — decoupling load and schema.
5. Any AI output is written to an advisory queue, never back into the system of record without human/legacy validation.

5 · Risk containment — flags, shadow mode & the kill switch

Ask yourself the question that decides whether you can sleep at night. It's 2 a.m., the AI path has started mis-triaging claims, and the pager goes off. How many claims are affected before you can stop it — ten, or ten thousand? How long until traffic is back on the safe legacy path — five seconds, or a five-hour incident bridge waiting on a deploy? Everything in this section exists to make those answers "a handful" and "seconds." That's what containment means: not preventing every mistake (you can't), but guaranteeing that any mistake stays small and is reversible fast.

The useful analogy is a ship's hull, which isn't one big open space but a series of sealed watertight compartments. A breach floods one compartment, the bulkheads hold, and the ship stays afloat — the design assumes damage will happen and limits how far it spreads. Your containment layer is the same idea applied to an AI retrofit: several independent mechanisms, each sealing off a different failure so no single problem can sink the whole platform. And crucially, they only work layered — a flag alone, or a kill switch alone, leaves gaps that the others cover.

Walk the layers from widest to narrowest, because each contains a different-shaped failure. A feature flag controls which slices or tenants ever see the AI path at all — default off, per-slice, so an unproven claim type simply never routes to AI. Shadow mode controls whether the AI's output is acted on or merely logged for comparison — the AI runs on real traffic but its answers stay invisible, letting you measure quality with zero risk. A circuit breaker guards against cascading failure: if the model gets slow or starts erroring, it trips automatically and sheds load back to legacy before the AI path drags claims processing down with it. A per-request legacy fallback catches the single failing request — a timeout or exception on one claim quietly serves the legacy result instead. And the kill switch is the master valve: one config change routes 100% of traffic back to pure legacy, in seconds, with no deploy. The mistake teams make is treating the kill switch as something to build after the first incident. It is a launch requirement — you must be able to demonstrate, in a rehearsed drill, that you can flip to 100% legacy in seconds before a single real claim touches the AI path. If you can't prove the rollback, you are not cleared to roll forward.

A retrofit lives or dies on containment: the blast radius of any AI mistake must be small and reversible. Four mechanisms, layered, give you that. Notice they're the same mechanisms a mature deployment uses everywhere — the retrofit just makes them non-negotiable because the legacy system is unforgiving.

6 · Incremental rollout — one slice at a time

You've now built every safety mechanism — and here is where teams throw them away. The pilot slice works, the demo dazzled leadership, and the ask comes: "It's clearly working, turn it on for everything next week." The pull to say yes is enormous, because momentum feels like progress. But "it worked on one slice" proves the mechanism works for that one claim type — it proves nothing about whether the AI generalizes to auto claims, or workers'-comp, or the weird catastrophe-claim edge cases, each with different data, different failure modes, and different risk. Enabling everything at once also throws away the entire point of the strangler-fig: it maximizes the blast radius you spent §3 and §5 shrinking. Speed in a retrofit does not come from skipping the gate; it comes from running the gate on many slices in parallel.

The discipline to hold is the one a doctor uses for a new medication: you don't dose the whole population on day one, you run staged trials, and each stage has to earn the next by clearing a pre-agreed bar. The bar here is always the same honest one — the legacy baseline, the old system's own numbers. You never grade the AI against a hoped-for target you invented; you grade it against what the legacy system already does today, because that's the bar the business is actually clearing right now. The stages climb in risk as trust accumulates: shadow (AI runs on one low-risk claim type, output logged and never used — does it agree with legacy?) → assist (AI drafts summaries a human sees and can reject — do adjusters accept them?) → expand (turn on more slices, each re-passing the shadow-then-assist gates) → steady state (enabled slices run with full monitoring). Notice the pattern: nothing acts on the AI's output until shadow proved it agrees, and nothing goes autonomous until assist proved humans trust it.

The rule that ties it together, and the one to say out loud in the leadership meeting: never enable a slice you couldn't instantly disable, and never advance a slice that hasn't beaten the baseline. Any slice that regresses below the legacy numbers gets flagged back off — no debate, no "let's give it another week." The rollback stays one config away at every single stage, which is what lets you move quickly because you can always undo. The table sequences the stages, the AI's scope at each, and the exact gate that advances it.

Now sequence the actual rollout. The strangler-fig only works if you grow the AI slice deliberately, measure each step against the legacy baseline, and keep the rollback one config away the whole time. Never enable a slice you couldn't instantly disable.

7 · Failure modes & the containment that hardens each

There's a tell that separates a design that will survive contact with production from one that won't. Sit a seasoned tech lead down in front of your architecture and they won't ask "how does it work when everything's fine?" — they'll ask "what happens when the model is down? when the read model goes stale? when the AI writes something wrong?" And here's the diagnostic: for a hardened design, every one of those answers points at a mechanism already in the architecture. For a fragile design, the answers are "hmm, we'd add a fallback" or "we'd probably build monitoring for that." A failure mode whose containment is something you'd bolt on after an incident is not a hypothetical — it is your next incident, already scheduled.

The way to think about this is the reverse of how you designed the system. You built the architecture forward — constraints, patterns, strangler-fig, plumbing, containment, rollout. Now you run it backward from the failures, the way an aviation safety engineer works: instead of asking "what should this do," you enumerate every way it can break and demand that each broken path already lands somewhere safe. This is a failure-mode-to-mechanism map, and its real value is as a completeness check — if you can name a failure with no matching containment, you've found the gap before the gap finds you. Good news for this retrofit: because §1–§6 derived each mechanism from a constraint, the map should be complete, and the table proves it by pairing each failure with the section that already hardens it.

Read the table as a set of promises the architecture keeps. Legacy coupling? The anti-corruption layer (§2) already isolates the AI. System-of-record corruption? The advisory-write queue (§4) means the AI never writes authoritative data. A big-bang blast radius? Per-slice flags (§3, §6) keep any one bug to one slice. Model outage or latency? The circuit breaker and legacy fallback (§5) shed load to the path that always works. A silent quality drop? Shadow comparison and per-slice baseline monitoring (§5, §6) catch drift before it spreads. No way back? The rehearsed kill switch (§5). Stale data? The CDC read model with freshness monitoring (§4). The common mistake this section guards against is a design that's beautiful in the happy path and silent about the failures — every row here is a failure you'd rather meet on paper than at 2 a.m.

A retrofit "designed for production" is one where every failure mode maps to a containment mechanism already in the architecture. If a row points at something you'd bolt on after an incident, that is your next incident.

route(request):
  if KILL_SWITCH_ON:                 return legacy(request)        # instant, config-only
  slice = classify_slice(request)
  if not flag_on(slice):             return legacy(request)        # slice not enabled
  try:
     ai = ai_path(request)                                          # reads via ACL/read model
     if SHADOW_MODE:  log_compare(ai, legacy(request)); return legacy(request)
     return ai
  except (Timeout, Error):           return legacy(request)        # circuit-breaker fallback