Anti-Corruption Layer
Pattern: A named solution to a recurring problem.
Translate between incompatible domain models so each side can keep its own vocabulary, rules, and structure.
Here, corruption means semantic contamination, not fraud. It happens when one system’s vocabulary and rules leak into another until the receiving model no longer says what its owners mean.
Type safety doesn’t prevent this. A vendor calls a customer an “account,” a legacy billing system calls a payment a “transaction,” and your code starts repeating both meanings. Soon the foreign vocabulary determines your own design.
Understand This First
• Bounded Context: defines where one model and vocabulary apply.
• Domain Model: captures the concepts and rules the layer must protect.
• Ubiquitous Language: gives each side the terms the layer translates between.
Context
Two systems need to work together, but they describe the world differently. One may be a legacy application you can’t change. Another may be a vendor API, a newly separated service, or a second bounded context owned by another team. Their payloads may be structurally compatible while their meanings aren’t.
This is an architectural problem. The risk isn’t that a field fails to parse. The risk is that foreign assumptions spread through your code until your domain model no longer reflects the business rules it was meant to express.
Problem
How do you integrate with another system without letting its model dictate your own?
Suppose a legacy order system uses customer for anyone who has ever requested a quote. Your new billing context uses customer only after identity checks and a signed agreement. Passing the legacy record straight through doesn’t merely reuse a data type. It smuggles in a different rule for who qualifies as a customer.
Forces
• The external or legacy system may be valuable even when its model is awkward, inconsistent, or outside your control.
• Reusing its client types throughout your code looks cheaper than maintaining a separate translation boundary.
• Translation must preserve meaning, not merely rename fields or convert formats.
• Every extra hop adds code, latency, monitoring needs, and another place where requests can fail.
• Coding agents treat available types and names as strong instructions, so imported vocabulary spreads quickly through generated code.
Solution
Put an anti-corruption layer between the models. Make it the only route across the boundary. The layer accepts each side’s native contract, translates the request or event, and returns a result expressed in the caller’s own language.
Keep foreign data-transfer objects, status codes, and error shapes inside the layer. The rest of your application should see internal entities and value objects. If the provider calls a parcel a consignment, the shipping context can still expose Shipment. If the provider uses five delivery codes but your domain recognizes three states, the layer owns that mapping and the policy for unknown values.
Translate in both directions where needed. Outbound translation converts internal commands into the external system’s protocol. Inbound translation validates its response, rejects impossible combinations, and constructs an internal result. Put tests around the semantic mappings: the cases where a term, status, amount, or lifecycle means something different on the other side.
The layer can be a small adapter inside one process, a module with a narrow interface, or a separate service. Choose the smallest form that owns the translation cleanly. Split it into a service only when independent deployment, scaling, or ownership earns the operational cost.
How It Plays Out
A retailer replaces a 20-year-old order application one capability at a time. The old system stores canceled orders as active rows with a cancellation flag. The new fulfillment context models cancellation as a terminal state. An anti-corruption layer reads the old row, applies the flag and date rules, and produces a valid FulfillmentOrder. New code never learns the legacy convention. During the Strangler Fig migration, the team can replace the old source without changing fulfillment’s contract.
A developer asks an agent to add a carrier integration. The generated client exposes provider types such as Consignment, ServiceLevelCode, and ExceptionReason. The instruction file tells the agent that those types must stay under integrations/carrier_x/. The agent writes a translator that returns the application’s Shipment, DeliveryPromise, and DeliveryFailure types, then tests every known carrier code plus the unknown-code path. When the carrier adds a new status, one mapping fails loudly instead of pushing an unfamiliar value through the codebase.
Warning: Don’t let generated client types cross the layer because they are convenient. Once internal modules depend on them, replacing the provider becomes a system-wide rewrite instead of one adapter change.
Consequences
Benefits
• Your internal model stays coherent even when outside systems use conflicting names and rules.
• Provider changes and legacy quirks remain concentrated in one place.
• Tests can state the semantic mapping explicitly, which gives both reviewers and coding agents a clear oracle.
• Migrations can proceed in small steps because new code doesn’t depend on the old model.
Liabilities
• You must write and maintain translation code, including cases neither model represents cleanly.
• The layer can become a bottleneck or single point of failure if every integration call passes through one overloaded service.
• Debugging crosses another boundary. Logs and traces must show both the external request and the internal meaning without exposing secrets.
• Two systems may disagree about timing or consistency in ways translation can’t hide. The layer should surface those differences instead of pretending they don’t exist.
Related Articles
Enforces: Ubiquitous Language — The layer converts foreign terms into the receiving context's ubiquitous language.
Implements: Boundary — The layer gives a semantic boundary an explicit implementation.
Supports: Domain Model — Translation keeps an external model from distorting the internal domain model.
Supports: Strangler Fig — A migration can replace legacy behavior behind an anti-corruption layer without exposing the old model to new code.
Uses: Bounded Context — An anti-corruption layer translates at the boundary between bounded contexts.
Uses: Contract — Each side meets the layer through a contract expressed in its own terms.
Sources
• Eric Evans introduced the Anti-Corruption Layer in Domain-Driven Design: Tackling Complexity in the Heart of Software (Addison-Wesley, 2003) as a way to keep another system’s model from corrupting a bounded context.
• Martin Fowler’s Bounded Context account explains why explicit mappings are necessary when the same concepts take different forms in different contexts.