When integrating a modern service with a legacy system (or an external system your team doesn't control) whose domain model is a poor fit for yours, what does an anti-corruption layer do, and what does it cost to maintain?

## What an anti-corruption layer is An **anti-corruption layer (ACL)** is a Domain-Driven Design pattern, introduced by Eric Evans, for the specific situation where your system needs to integrate with another system — often legacy, a third-party product, or another team's bounded context — whose domain model, terminology, or data quality doesn't match yours, and where letting that mismatch leak directly into your codebase would degrade your own model over time. Mechanically, the ACL is a dedicated translation boundary: a module, adapter, or set of facade classes that sits between your code and the external system, whose entire job is converting between 'their' representation and 'yours' at every crossing. Nothing on your side of the ACL touches the external system's raw types, field names, status codes, or quirks directly — your domain code calls a clean interface expressed in your own ubiquitous language, and the ACL is the only place that knows both vocabularies. ## Why the pattern exists The reason this pattern exists is that integration boundaries are where model corruption happens by default. If you don't deliberately translate, the path of least resistance is for your code to use the external system's DTOs, enums, and field names directly wherever convenient — and once that starts, it spreads: - your domain logic ends up littered with conditionals for the legacy system's edge cases - your own domain concepts get bent to match the external system's shape instead of the shape actually correct for your problem - and eventually you can't tell which parts of your 'domain model' reflect your actual business rules versus accidental inheritance from someone else's legacy system The ACL draws a hard line: corruption is allowed to exist in the adapter code, but not to cross into the domain core. ## The trade-off The trade-off is genuine engineering cost versus long-term model integrity. Building an ACL means writing real translation logic — often including validation, defaulting for missing fields, reconciling inconsistent status vocabularies, and sometimes compensating for the external system's outright bugs — plus tests for that translation logic, and someone has to own it as its own piece of software with its own failure modes. For a small, clean, well-documented integration this is overkill: wrapping a well-designed external API's DTOs one-to-one with an ACL just to satisfy the pattern adds indirection with no real translation happening, which is wasted effort. The pattern earns its cost specifically when the external model is genuinely messy, unstable, or conceptually foreign to your domain — a legacy mainframe with decades of undocumented status-code meanings is the canonical case, but a third-party SaaS with a data model shaped around their product's history rather than your domain is another common one. ## The payoff over time The payoff shows up over time, not immediately: because your domain model never directly depends on the external system's shape, that system can change its API, get replaced entirely, or be migrated off gradually, and the blast radius is confined to the ACL. If you'd instead let the legacy model leak into your core, replacing that system becomes a project that touches your entire codebase, because your domain logic is riddled with assumptions baked in from a system you're trying to get rid of. This is especially valuable in a **Strangler Fig migration**, where a team incrementally replaces a legacy system: the ACL lets new code be written against a clean target model from day one, routing through the ACL to the old system for now and later re-pointing the same ACL interface to the new system, with zero changes needed in the domain code that consumes it. ## Failure modes on both sides of misuse Failure modes show up on both sides of misuse. | The misuse | What it produces | |---|---| | **Under-using the pattern** — skipping the ACL and wiring legacy DTOs straight into domain logic | produces the corruption described above: brittle domain code, conceptual confusion between what the business actually needs and what an old system happens to expose, and an expensive, risky legacy-replacement project down the line | | **Over-using it** — building an elaborate ACL for a clean, stable, well-modeled integration | produces unnecessary indirection and extra code to maintain, adding cognitive overhead without protecting anything meaningful | | **A subtler failure** — building an ACL that's too thin | translating field names but not concepts, so the legacy system's actual business assumptions still leak through the interface even though the syntax looks clean | ## A concrete real-world scenario A concrete real-world scenario: a retailer migrating off a 20-year-old mainframe order-management system builds a modern order service with its own clean Order aggregate (states: placed, fulfilled, cancelled, refunded). The mainframe exposes orders through a rigid legacy interface with seventeen numeric status codes, several of which map to the same modern concept and a few of which are dead codes nobody remembers the meaning of. The ACL is the one module that talks to the mainframe directly, translates those seventeen codes into the four clean states the domain actually needs, and absorbs every future oddity discovered in production — so when the retailer eventually decommissions the mainframe, only the ACL's implementation is replaced; the order domain logic, and everything built on top of it, never has to change.