Skip to content
System Design Lab
Microservice Patterns

Anti-Corruption Layer

Put a translating façade between a new system and a legacy one, so the legacy model, protocols and quirks stay on the other side — and so you can cache, batch and protect the legacy system on the way.

Intermediate 4 min read· Updated 2026-11-18

What you will learn

  • Explain how a legacy model leaks into new code without a boundary.
  • Design an anti-corruption layer that translates models and protocols.
  • Reduce load on the legacy system with caching and coarse calls.
  • Use the layer as a seam for gradual migration.

Before you start

Overview

When a company works with a foreign partner, it hires an interpreter instead of asking every employee to learn the partner's language and customs. Staff speak plainly; the interpreter handles the translation — and notices when the same question was answered yesterday.

New services often must talk to a legacy system — an ERP, a mainframe, a third-party API — whose model does not match theirs (different names, codes, granularity, protocols such as SOAP or files). An anti-corruption layer (ACL) is a façade that exposes the new system's own model and translates to and from the legacy one. Nothing outside the ACL depends on legacy types.

Run it

In A the new Orders service makes four granular calls per order straight into the ERP. In B one clean call goes to the ACL, which caches reference data and makes one ERP call. Compare Calls the ERP had to serve and latency, then slow the ERP down.

Loading simulation…

What the layer does

  • Translate models: CUST_NO and ORD_HDR become Customer and Order; codes become enums.
  • Translate protocols: REST/events on the new side, SOAP, files or screen scraping on the old.
  • Shape calls: one coarse operation instead of several chatty ones; batch where possible.
  • Protect the legacy system: cache reference data, limit concurrency, apply timeouts and circuit breaking.
  • Contain quirks: retries for known flaky operations, error-code mapping, data cleaning.

Implementation sketch

The new model in, the legacy protocol out
public interface OrderPlacement {                       // the new domain's port
    PlacedOrder place(NewOrder order);
}

@Component
class ErpOrderPlacement implements OrderPlacement {     // the anti-corruption layer
    private final ErpSoapClient erp;
    private final Cache<String, ErpCustomer> customers;  // reference data rarely changes

    public PlacedOrder place(NewOrder order) {
        ErpCustomer customer = customers.get(order.customerId(), erp::findCustomer);
        OrdHdr header = OrdHdr.of(customer.custNo(), order.lines().stream().map(this::toErpLine).toList());
        ErpResult result = erp.createOrder(header);        // one coarse legacy call
        if (result.rc() != 0) throw translate(result);     // legacy error codes → domain exceptions
        return new PlacedOrder(result.ordNo().trim(), OrderStatus.from(result.stat()));
    }
}

Trade-offs

BenefitsCosts
Model integrityNew code stays clean and expressed in its own language.Translation code to write, test and keep in sync with both sides.
LoadCaching and coarse calls protect a fragile legacy system.Cached data can be stale; invalidation needs thought.
OperationsOne place to monitor and tune legacy integration.An extra hop and possibly another service to run and scale.

Production considerations

  • Own the ACL in the team that owns the new model, not the legacy team.
  • Contract-test both sides: the new interface and the legacy behaviour it depends on.
  • Apply timeouts, concurrency limits and a circuit breaker towards the legacy system.
  • Log raw legacy requests and responses (redacted) — invaluable when the legacy behaves unexpectedly.

Further reading

Related topics