Anti-Corruption Layer

Protect the domain boundary

An anti-corruption layer translates between one system's model and another bounded context's language. It is useful when integrating with a legacy application, vendor API, or external domain whose concepts do not match the new system's domain model. Without an explicit boundary, external field names, status codes, lifecycle assumptions, and error behavior spread into application code. The new system becomes shaped by constraints it does not own.

The layer can include an adapter for transport, a translator for domain concepts, and a mapper for errors. These responsibilities may live in a small module or service depending on the boundary and operational need. A translator might convert an external account state such as SUSPENDED_BY_RISK into an internal AccountStatus with a clear meaning. It should not simply rename every external type and call the integration isolated; the goal is to preserve the local domain language and make semantic differences explicit.

Translate behavior, not only fields

Model translation includes lifecycle and failure semantics. A vendor may return a success response before an operation is fully settled, use a sentinel value for missing data, or retry requests with its own idempotency rules. The boundary should make those behaviors visible to the domain and protect local invariants. Map external errors into stable internal outcomes, retaining diagnostic context for operators without leaking vendor-specific details throughout business logic.

Do not discard information that the domain needs. If an external status has no exact internal equivalent, define a mapping policy and record unknown values safely. An exhaustive mapping can fail closed for an unexpected enum rather than silently treating it as active. Log or meter unknown values so a vendor change is detected. Keep sensitive payloads out of logs and preserve correlation identifiers for support.

Place the boundary intentionally

The layer belongs at the integration boundary, close enough to contain external contracts but not so entangled with the domain that vendor details leak through its interface. A domain service should depend on a local port or application contract; an adapter implements that contract using the external client. This makes tests independent of the vendor and allows a replacement to be evaluated without rewriting every use case.

An anti-corruption layer is not a universal wrapper around every dependency. If an external system's model already matches the local domain and the integration is stable, a direct client can be simpler. A translation layer adds code, tests, monitoring, and ownership. Introduce it when semantic mismatch or change isolation justifies that cost. Avoid building speculative abstractions for hypothetical future vendors; model the actual variation the system must handle.

Operate and evolve the integration

The boundary should expose timeout, retry, rate-limit, and idempotency policy explicitly. Translate transport failures into domain-appropriate outcomes while preserving the ability to distinguish transient failure from invalid input. Avoid unbounded retries or translating every error into a generic success-like state. If the external system is unavailable, decide whether the use case can queue work, return a pending result, or must fail.

Test translations with contract examples from the external service and local domain invariants. Include unknown values, missing fields, duplicate events, and error responses. Contract tests can detect provider changes; unit tests can verify that the translation preserves meaning. Monitor latency, error rates, unknown enum values, and quota use at the boundary. A well-owned layer reduces coupling only if it remains aligned with both contracts.

Translate a legacy customer contract

Suppose a legacy customer system exposes a response with fields CUSTOMER_NO, ACCT_STATE, and RISK_CODE. The new service uses CustomerId, AccountStatus, and a local risk policy. Do not pass the legacy response object into the domain model. Define an adapter that calls the legacy API and a translator that constructs the local value object. Keep the external DTO at the edge so a legacy field rename has one place to change.

Map states explicitly. ACTIVE may map to enabled, CLOSED to closed, and a risk hold to restricted with an associated reason. If the legacy service returns an unfamiliar status, do not default to enabled. Return a controlled integration error or an explicit unknown state that the use case handles safely, and emit a metric for investigation. Preserve a correlation id so support can trace the upstream interaction without logging sensitive customer data.

Make failures and side effects explicit

If an operation creates a customer in the legacy system, define idempotency and retry behavior. A timeout can occur after the legacy service committed the record. A blind retry may create a duplicate. Use an idempotency key if supported, or implement reconciliation that can locate the prior result. Map rate limits and transient unavailability into retryable outcomes with bounded backoff; map validation errors into domain-level feedback that the caller can act on.

Keep transport concerns such as HTTP codes and JSON parsing in the adapter. The translator should map known response semantics. The application service should express a use case in local terms. This separation allows a unit test to provide a fake local port and focus on domain behavior, while adapter tests verify the external contract and translator tests cover mappings.

Verify the boundary

Create representative contract fixtures for each external state and error. Test unknown enum values, absent optional fields, changed casing, and an upstream response that is syntactically valid but semantically contradictory. Test duplicate delivery for event integrations and timeout-after-commit for command integrations. A passing happy-path test alone does not prove the boundary prevents external assumptions from leaking inward.

Monitor the adapter in production. Track latency, failure class, rate-limit responses, unknown values, and retry counts. Alert when the external contract changes in a way that blocks a critical workflow, but avoid paging on every malformed optional field if the domain can safely proceed. Define an owner for provider changes and a process to update fixtures when the vendor publishes a new API version.

Evaluate whether the layer is worth its cost

If the vendor model is identical to the local model and unlikely to change, a simple client may be enough. If multiple use cases are translating the same state differently, a shared boundary can reduce duplication. If the layer contains dozens of pass-through methods and no semantic mapping, it may be abstraction without protection. Review the interface: can a domain test use it without importing vendor types? Can the provider change be localized? Those are useful signals that the boundary is doing real work.

Document which concepts are intentionally translated and which are preserved. This prevents a future developer from bypassing the adapter to access a field that appears convenient but carries external semantics. The layer is successful when local invariants stay local, integration behavior remains observable, and changes at one boundary do not ripple through the system.

Do not confuse mapping with isolation

Renaming an external DTO does not create meaningful isolation if the new model preserves all of the same external assumptions. The boundary must translate concepts, lifecycle, errors, and consistency where they differ. Conversely, translating every field into a new type can add ceremony without protecting the domain. Start from a concrete mismatch and define the local invariant that should remain stable if the external contract changes.

An anti-corruption layer has an ownership cost. Someone must maintain mappings, fixtures, provider compatibility, metrics, and failure policies. It can also hide useful provider capability if the local interface is too narrow. Make extension needs explicit and keep provider-specific features behind an intentional escape hatch rather than leaking them into every caller.

Make change and failure testable

The boundary should provide a clear place to test unknown statuses, retries, idempotency, and error conversion. Contract tests catch upstream drift, while local unit tests verify that domain behavior does not depend on transport DTOs. Monitor the layer so semantic surprises are visible. Without observability, isolation can make a provider problem harder to diagnose rather than easier.

In an interview, identify the model mismatch, show the adapter and translator boundary, and explain the mapping of one success and one failure. Discuss what happens on an unknown external state and how the design avoids duplicate side effects. Then explain why a simpler client would be adequate if the models already matched. This demonstrates that the pattern is used to contain real semantic coupling, not applied as a mandatory wrapper around every API.

A useful boundary has an explicit contract. Define local operations in domain terms, specify which external statuses are mapped, and state what happens when the provider returns a value that the local model cannot represent. Preserve a stable error category for callers while attaching safe diagnostic metadata for operators. This prevents each use case from inventing a slightly different translation. Version the adapter when the provider changes behavior and test compatibility before rollout.

Do not let the layer become a pass-through proxy that exposes every vendor endpoint. That makes callers dependent on the external contract even though a translation module exists. Nor should the layer absorb unrelated business rules that belong to a domain service. Its responsibility is to map concepts and interaction semantics at a boundary; a domain policy decides what the translated information means for a local use case.

Choose the minimum interface that protects a meaningful invariant. If another vendor is only hypothetical, avoid designing a broad provider-neutral API in advance. If two actual providers expose distinct capabilities, represent the common behavior and make capability differences explicit rather than hiding them in flags. Measure the maintenance cost of mappings and contract fixtures against the reduction in change ripple. Retire unused mappings when the integration changes, but keep the local domain stable.

In a review, trace one command and one failure from the external protocol to the caller's local behavior. Ask whether an upstream schema change can be contained, whether a retry can duplicate an effect, and whether an operator can see an unknown response. These checks reveal whether the layer creates real isolation or only another hop. Tie the answer to test coverage and production metrics so the boundary remains observable as well as decoupled.