Anti-Corruption Layer

The Anti-Corruption Layer is a pattern from Domain-Driven Design (DDD), introduced by Eric Evans. The metaphor: you're building a new, clean system (a city). Next door is a legacy system (a polluted industrial site). You don't want the pollution leaking into your city, so you build a wall with a controlled checkpoint — everything that crosses the boundary is cleaned, filtered, translated. That checkpoint is the ACL.

Concretely, the ACL is a service (or a layer within a service) that sits between your new code and the legacy system:

• The new system calls the ACL using its own clean domain model.
• The ACL translates the call into the legacy's protocol, schema, and conventions.
• The ACL calls the legacy.
• The legacy responds in its own (often ugly) format.
• The ACL translates the response back into the new system's clean model.
• The new system receives a clean object, unaware of the legacy's existence.

The new system's code never imports legacy types, never names legacy fields, never inherits legacy's error conventions. It only sees its own model. The legacy's quirks — its PascalCase JSON, its cryptic error codes, its status enums like 'PARTL' and 'CNCL' — live and die inside the ACL.

This pattern is essential during Strangler Fig migrations: each new service that needs to call legacy wraps the calls in an ACL, so the new service is built on clean concepts from day one. When the legacy is eventually retired, the ACL is removed — and the new service is already clean.

An ACL translates more than just data shapes. It translates:

• Data schemas: new system's Order.id (UUID) ↔ legacy's ord_id (CHAR(8)).
• Status enums: new system's OrderStatus.PAID ↔ legacy's stts_cd = 'PD'. The new system has meaningful enum values; the legacy's cryptic codes live in the ACL.
• Units and types: new system's totalCents (int) ↔ legacy's tot_amt (DECIMAL dollars). The ACL handles precision and rounding rules.
• Protocols: new system calls via typed gRPC; legacy is a SOAP service or a stored procedure. The ACL speaks both.
• Error conventions: new system throws typed exceptions; legacy returns retcode 0/1/2/3. The ACL maps.
• Naming and vocabulary: new system uses the business's current language (‘customer’, ‘subscription’); legacy uses outdated terms (‘acct’, ‘svc_plan’). The ACL renames.
• Business rules: legacy may require a side-effect (writing to an audit table) that the new system shouldn't have to know about. The ACL hides it.
• Pagination, filtering, sorting conventions: new system uses standard ?limit=10&offset=20; legacy uses a custom ?pg=2&sz=10 or no pagination at all.

The ACL is also a place to enforce invariants the legacy doesn't: validation, idempotency keys, rate limiting, observability. The new system gets a clean, well-behaved API; the legacy is left alone.

Where does the ACL live?

• As a separate service — a dedicated microservice that exposes a clean API and calls legacy. Other services call it, never the legacy. Easiest to reason about; some operational overhead.
• As a library within the new service — the new service imports a legacy-adapter module that handles translation. Lower overhead; couples the new service to the adapter's release cycle.
• As a sidecar — the ACL runs in a sidecar container alongside the new service. Useful if the ACL needs its own language (e.g., it must call SOAP and the new service is gRPC-native).
• As a layer in a façade / API gateway — if the gateway supports transformation logic (e.g., Kong plugins, API Gateway mapping templates).

Implementation tips:

• The ACL is its own bounded context. It owns the translation logic and the legacy's quirks. Don't spread translation across services.
• Test the ACL with contract tests on both sides. The legacy side is fixed (you can't change it); the new side is your contract with new services.
• The ACL is throwaway. When legacy is retired, delete the ACL. Don't build anything into the ACL you'd want to keep — that goes in the new system.
• Keep the ACL thin. Don't put business logic in it; that belongs in the new system. The ACL translates, it doesn't decide.
• Make the ACL observable. Translation bugs surface as ‘why did this call fail?’ — log both the clean request and the legacy request, with correlation IDs.

A common failure: the ACL becomes a god-object that knows too much. Resist this. The ACL is a translator, not a business layer.

Mental model. Think of Anti-Corruption Layer as a deliberate boundary in a system. The boundary exists because something becomes harder to manage when everything is done in one place: latency, scale, failure isolation, consistency, cost, or team ownership. The useful question is not “what does Anti-Corruption Layer mean?” but “what pressure makes this boundary worth introducing, and what new failure mode does it create?”

Numerical lens: write down traffic, payload size, read/write ratio, peak multiplier and durability target before choosing a component. The numbers should justify the architecture.

Answer this without notes: When would you choose Anti-Corruption Layer, and when would you intentionally avoid it? Mention at least one bottleneck it addresses, one failure mode it introduces, and one alternative. Then quantify the workload you are designing for.

Numerical sanity check

Back-of-the-envelope reasoning beats fake precision. State your traffic, payload, concurrency and growth assumptions explicitly, then calculate enough to know whether the current architecture is orders of magnitude away from the target.