Anti-Corruption Layer: The Missing Piece in Every Legacy Rewrite

Meta: "The anti-corruption layer is the pattern most teams skip during legacy rewrites and why their new system inherits the old system's worst problems."

T

Forty minutes in, the tech lead put down his coffee and asked a question nobody in the room wanted to answer: "Why does our new service have a field called legacy_order_ref_id?"

Silence.

Six months into the rewrite. New stack, new architecture, new database schema. The whole point was to get away from the old system's data model a model that had accumulated five years of business logic buried in column names, numeric status codes with meanings nobody had written down, and foreign key relationships that implied rules the domain team had forgotten existed.

And here it was. In the new code. legacy_order_ref_id.

This is how legacy systems colonize the things built to replace them. Not through any single bad decision, but through a hundred small accommodations made while the old system was still running. You need data from the legacy system to process an order, so you pass the field through. Then you add an if-statement to handle the case where it's null. Then another engineer adds a lookup table that maps the old status codes to the new ones, right there in the service. Three months later, your new system is fluent in legacy.

The pattern that prevents this is called an anti-corruption layer. Most teams skip it. Most teams regret that later.

Why Rewrites Absorb the Systems They Replace

When you start a legacy rewrite, the old system is still in production. Users are on it. Revenue depends on it. You can't turn it off. So the new system has to talk to it to read data, sync state, hand off requests.

Every time the new system calls the old one, it has to speak the old system's language. Legacy APIs return data in formats shaped by decisions made years ago, for reasons that no longer apply. Status codes that mean three different things depending on context. Date fields stored as strings in DD/MM/YYYY format because that's what the original PHP script expected. Customer IDs that are integers in one table and UUIDs in another because the system was migrated halfway in 2019 and nobody finished.

If you let the new system call the legacy API directly and map the responses inline, the old data model bleeds in. Engineers working on the new codebase start learning the old system's quirks just to understand the new one. The conceptual debt transfers.

The anti-corruption layer (ACL) is a boundary. It sits between the new system and the legacy system and translates converting legacy concepts, data formats, and structures into the new domain's language before anything enters the new system. The new system never sees a legacy_order_ref_id. It sees an order_id. The translation happens in the ACL, once, explicitly.

What an Anti-Corruption Layer Actually Is

The concept comes from Domain-Driven Design. The original framing: when two bounded contexts with different domain models need to communicate, you build a translation layer at the boundary rather than letting one model contaminate the other.

In practice, an ACL is usually a service or a module with a narrow, explicit job: receive data from the legacy system in the legacy format, translate it into the new domain's types and concepts, and return something the new system can reason about without knowing anything about the source.

It typically implements two patterns underneath: an adapter and a facade.

The adapter converts data transforms the legacy status code 3 into the new domain's OrderStatus.AWAITING_DISPATCH. Converts the string date to a proper datetime. Maps the integer customer ID to a UUID. This is mechanical, but it has to live somewhere. The ACL is the right place.

The facade presents a clean interface to the new system. Instead of exposing "here is the legacy endpoint, call it and then do this parsing logic", the facade exposes get_order(order_id: UUID) -> Order. The new system calls that. What happens inside the HTTP call to the legacy API, the response parsing, the field remapping is the ACL's problem.

The new system's codebase stays clean. Engineers working on new features don't need to know that legacy_order_ref_id exists.

How to Implement It Without Overengineering

The ACL doesn't need to be a separate deployed service. For most teams doing a legacy rewrite, it starts as a module within the new service a dedicated package or namespace with a clear boundary. The rule is: nothing outside this module ever imports from it and then manipulates the data further. If you find yourself calling acl.get_order() and then doing additional mapping on the result, the ACL isn't doing its job.

Concretely, the structure looks like this:

new-service/
  domain/
    order.go         # Order type, OrderStatus enum, domain logic
  legacy/
    client.go        # HTTP client for legacy API
    mapper.go        # Converts legacy response → domain.Order
    facade.go        # Public interface: get_order, list_orders, etc.
  handlers/
    order_handler.go # Calls legacy.facade, never legacy.client directly

The handlers layer never imports from legacy/client.go or legacy/mapper.go. It only touches the facade. If a new engineer joins and wants to understand how order retrieval works, they read domain/order.go and legacy/facade.go. The mapping complexity is contained.

For the rewrite using a Strangler Fig approach incrementally replacing the legacy system piece by piece the ACL also gives you a clean cut point. When you've fully migrated orders to the new system, you delete the ACL for orders. You don't have to hunt through the codebase for all the places that were doing if legacy_order_ref_id != null checks.

The Part Most Teams Get Wrong

Two failure modes. Both common.

The first: skipping the ACL because "we're going to rewrite everything anyway, so it doesn't matter if some legacy concepts leak through in the interim." This is how interim becomes permanent. The rewrite takes longer than planned (it always does). The team grows during the rewrite. New engineers onboard to a codebase that's half-legacy, half-new, with no clear boundary between them. The legacy_order_ref_id field gets used in four more places. Now it's a permanent fixture.

The second failure mode is the opposite: making the ACL too thick. If the ACL contains business logic not just data translation but actual decisions about how the domain should behave it becomes a third system to maintain alongside the legacy and the new one. The ACL should translate. It shouldn't decide.

A useful test: can a junior engineer understand exactly what the ACL does without understanding either the legacy system's business rules or the new domain's rules? If yes, the ACL is doing translation. If no, business logic has leaked in.

The other gotcha is forgetting to plan for the ACL's removal. The ACL is a scaffold, not a permanent structure. As you migrate more of the legacy system, ACL modules should shrink and eventually disappear. If there's no owner responsible for tracking that, the ACL persists after the migration is complete another layer of indirection with no purpose, left because nobody agreed it was done.

What a Jakarta Logistics Platform Learned the Hard Way

A logistics platform in Jakarta mid-series B, processing around 40,000 shipments per day started their rewrite in early 2019. PHP monolith, six years old. Moving to a Go microservices architecture, starting with the shipment tracking service.

In the first two months, they built the new tracking service directly integrated with the legacy system's MySQL database. It seemed efficient. Direct DB reads, no API boundary to maintain.

By month four, the new tracking service had accumulated twenty-three queries against legacy tables. It knew about a status field that used integer codes 1 through 9, with no documentation, where 4 and 7 both meant "in transit" under different carrier contracts. It had reproduced a bug in the legacy system a date offset issue because the downstream analytics dashboard expected the bug to be there.

When they brought in a consultant to assess the rewrite, the verdict was direct: the new service was not a replacement for the legacy tracking system. It was the legacy tracking system with better tooling around it.

They spent six weeks extracting an ACL pulling the direct database queries behind a facade that returned clean Shipment domain objects, centralising the integer-to-status translation, fixing the date bug in one place. The consultant's observation afterwards: "Now you're actually ready to start the rewrite."

The ACL doesn't save you from the difficulty of understanding the legacy system. You still have to understand it to write the translators. What it saves you from is that understanding spreading across the codebase into every engineer who ever touches the new system.

FAQ

Q: Is an anti-corruption layer the same thing as an API gateway? A: No. An API gateway handles routing, rate limiting, and authentication for external clients. An anti-corruption layer is an internal boundary that translates between two domain models it's specifically about protecting a domain from a foreign model's concepts. They can coexist, but they solve different problems.

Q: Do I need an ACL if we're doing a big-bang rewrite instead of a gradual migration? A: Yes, for a different reason. In a big-bang rewrite, the new system still needs to be seeded with data from the legacy system either through a migration script or through dual-running periods. If the data migration maps legacy concepts directly into the new schema without going through a translation layer, you've hardcoded the legacy model into your migration. The ACL gives you an explicit place to catch and fix legacy data issues before they enter the new database.

Q: How does this interact with CQRS? A: Well, in specific ways. If you're using CQRS on the new system, your read model might be sourced from the legacy system during the transition. The ACL sits between the legacy data source and the CQRS read-side projections. The projections receive clean domain events, not raw legacy data. This keeps the read model honest even while the write side is being migrated.

Q: How do we decide where the ACL boundary should be? A: Draw it at the service boundary, not the data field boundary. The question isn't "which fields are legacy?" but "which capabilities are we still getting from the legacy system?" Each legacy capability gets an ACL facade. When you've migrated a capability fully to the new system, you remove that facade. The boundary tracks your migration progress.

Q: We're not doing a full rewrite just modernizing the frontend and leaving the backend alone. Do we need this? A: If your new frontend needs to call legacy backend APIs, yes though the ACL in this case might be a BFF (Backend for Frontend) layer that translates legacy API responses into a shape the new frontend can work with cleanly. The concept is the same. You're protecting the new domain from the old one's data model. Where that boundary lives depends on your architecture, not the pattern itself.

The systems that are hardest to rewrite aren't the technically complex ones. They're the ones where nobody built a clear boundary between what the legacy system knew and what the new one needed to know. By the time someone tries to draw that line, it runs through the middle of everything.

If you're starting a legacy migration and wondering whether an architecture review makes sense before the first line of new code is written, that's precisely where a second opinion pays for itself.

Internal links used:

• Strangler Fig approach natural connection to the migration pattern this supports
• CQRS on the new system FAQ answer on interaction with CQRS
• that's precisely where a second opinion pays for itself closing CTA, same article, different anchor text

External links used:

• None

Word count: ~1,980

Self-Review Scorecard