Anti-corruption layers: adapters to save us all

An anticorruption layer is a layer that prevents us to corrupt our own domain because of the domain of an external partner or dependency.


Domain-Driven Design and Hexagonal Architecture

Related tags

ddd, hexagonal architecture, domain-driven design, context mapping


An anticorruption layer is a layer that prevents us to corrupt our own domain because of the domain of an external partner or dependency.

Coupling our domain with other's

When we integrate our software with external's ones, we have the risk of corrupting our own domain by introducing the external one in our code. This means that we are going to accept foreign concepts as if they were part of our domain model.

For example, let's say we are integrating an external CRM including Leads, Contacts, and Companies, and we just replicate the very same structure of the CRM, without spending any time on abstracting concepts, using the integer-based identifiers of the CRM while we are using UUID's on our domain, or we call from our frontend directly to their API's... did you recognize this situation?

What would happen if we want to change our CRM provider?

An anticorruption layer as the first defense against provider coupling

To avoid the situation described above, we should create a layer between us and the provider: this is the so-called anticorruption layer. This layer works as an adapter, transforming our own representation of the domain and the external's provider. In our previous example, we need to create our own entities for Leads, Contacts, or Companies, and then synchronize information through APIs or messaging queues or any other method, so we are using our own domain but the provider's data.

What about the external IDs? We should save a mapping table, so the adapter synchronizes information and can use it to relate our entities with the external ones. This is called context mapping.

Frontend, then, should only call our own APIs, which in turn can call the provider's, acting as a proxy.

If we need to change our provider, we need only to change the adapter, the proxy between us and the previous provider, adding another for the new one. That's it, the anticorruption layer.

Generalization of the concept

You can generalize the concept so an anticorruption layer can not only isolate you from your provider's domain, but also from other layers of your own domain. For example, use Commands and Queries to isolate the Application layer from the Infrastructure one, or Domain Services to isolate the Domain layer from the Application one.


I once heard a case where a company coupled their internal user's IDs with an external CRM; one day, this external provider decided to change the IDs from numeric ones to UUID-based ones. You can imagine the situation, the IDs were spread by hundreds of relationships throughout the whole database. The migration took weeks and the product was completely stopped during this time.

So... please, use anticorruption layers.

Not another newsletter

  • A montly summary of everything new in the blog: So you can consume the content at your own pace.
  • Discounts on my books or courses: You will have exclusive discounts on books, courses or any other pay material I build in the future.
  • Books recommendations: I will recommend you books time to time, only the best of the best.

Join to get more like this

Only one email per month, period. Unsubscribe any time.