Anti-Corruption Layer

In practice

Without one, a vendor's model becomes your model. Their PARTY_TYPE_CD = '03' and their nine-field date representation propagate into your services, your database and eventually your UI — and when the vendor is replaced three years later, the migration touches everything.

With one, the shape is:

your domain  ->  Translator  ->  vendor client  ->  vendor API
   Customer       maps fields      their SDK        their model

The translator owns: field mapping, unit and enum conversion, error translation to your own error types, retry and timeout policy, and a fake implementation for tests. That last one is underrated — an ACL makes the external system trivially mockable, because the boundary is an interface you defined.

The cost is real: an extra hop of code, duplicated-looking models, and a mapping to maintain. It is worth paying when the external model is bad, unstable, or likely to be replaced. It is not worth paying for a stable internal service whose model you already agree with.

When it matters

Legacy integration, third-party SaaS, mainframe access, and every strangler fig migration — the ACL is what lets the new system have a clean model while the old one still exists.

Common mistake

Building the layer and then leaking the vendor's types through it — returning their DTO from your repository interface. If the vendor's class name appears in your domain code, the layer is decoration.