The story of the translator at the gate

Imagine you are a .NET developer at a mid-sized retail company in Colombo. Your team has been tasked with building a brand new e-commerce platform from scratch using ASP.NET Core, Entity Framework Core, and C#. You are doing everything right: clean architecture, DDD principles, proper bounded contexts. Your “order” domain is expressive and clean.

Every class name, every method, every property matches exactly what your business stakeholders say in meetings. Your domain speaks the language of the business. Life is good.

Then your manager walks in with a familiar smile.

“We need to integrate with the existing Dynamics NAV system. Oh, and the old inventory service built in .NET Framework 4.5. And we’re adding PayHere for payments.”

You stare at your beautiful “order” class and feel something cold creeping in.

The Legacy Monster: Dynamics NAV

The company has been running Microsoft Dynamics NAV for inventory, finance, and customer records for over a decade. It works. Nobody touches it. Nobody dares to touch it. But your new platform needs to talk to it, to check stock levels, trigger invoices, and sync customer records.

You add the service reference in Visual Studio. The auto-generated proxy classes arrive like uninvited guests.

Fields with underscores. Dates as strings. Status as magic strings. “No” meaning ID. “LCY” meaning local currency. A “Sales_Header” meaning what your domain calls an “Order”.

The developer who said “It’s just a few fields”

One of your junior developers, under deadline pressure, makes a decision that seems harmless at the time. Instead of building a proper translation layer, he maps the NAV fields directly into the domain model. It is faster. It ships on time.

It ships. The integration works. Three weeks of silence.

Then a new developer joins. He opens “ProcessOrderAsync” and asks: “What is a ”Sales_Header"? Why is our “OrderService” returning a ”Sales_Header"? What does “Released” mean? Is that our status or NAV's?"

Then, NAV gets upgraded from version 2013 to Business Central. The SOAP service changes. “Satus = Released” becomes “Status = '3'". The entire application breaks because a dozen files were checking that magic string.

Then the team tries to write a unit test for “ProcessOrderAsync”. The method depends on a SOAP client proxy. The test setup becomes a nightmare of mocking auto-generated WSDL proxies that were never designed to be mocked.

This is the corruption. Quiet, gradual, and by the time you notice it, it is everywhere.

Building the Anti-Corruption Layer in .NET

A senior developer on the team steps in. He creates a clean structure inside the infrastructure layer.

He defines the domain contract in the domain’s own language

He defines an interface for the Adapter so it can be tested and swapped independently

He writes the concrete SOAP client

He writes the Adapter, the true Anti-Corruption Layer

He writes the Gateway. The concrete SOAP client is injected directly. The Adapter is injected through its interface

And separately, the true Repository that talks to the team’s own database

The application service works entirely in clean domain language. No trace of NAV, no SOAP proxies, no magic strings

Unit testing becomes trivial. Every important dependency is an interface, and every interface is mockable

No SOAP. No WSDL proxies. No magic strings. Just clean interfaces, clean domain behaviour, and tests that run in milliseconds.

Three months later, NAV gets upgraded. “Released” becomes “3”. One switch statement in “NavOrderAdapter” is updated. The Gateway does not notice. The application handler does not notice. The domain does not notice. The business keeps running.

The Anti-Corruption Layer just earned its place.

The Second Crisis: .NET Framework 4.5 Inventory Service

The company also has an old inventory service built years ago in .NET Framework 4.5. It exposes a REST API but returns responses shaped by ancient conventions: Hungarian notation field names, amounts as doubles, dates as oddly formatted strings, and status as integer codes.

Without an ACL, this JSON shape starts leaking into the domain. The “Product” entity starts growing “strItemCode” and “intQtyOnHand” properties. Hungarian notation, abandoned by the .NET community over a decade ago, resurfaces in the shiny new codebase. A “double” representing money floats around where a proper “Money” value object should live.

The same pattern is applied. An interface for the Adapter. A Gateway for communication. An Adapter for translation.

The domain works with “StockLevel” a clean value object with meaningful names. “strItemCode” never crosses the boundary. “dblUnitCost” never crosses the boundary. “intStatusCode == 1” never appears in business logic.

When the company eventually rewrites the old inventory service in modern .NET 8, only the “LegacyInventoryAdapter” and the “LegacyInventoryHttpClient” change. The domain and all application logic built on top of them remain untouched.

The Third Crisis: PayHere Payment Gateway

The team integrates PayHere, a popular Sri Lankan payment gateway. PayHere sends a webhook notification when a payment completes.

Amount as a string. Status as a numeric string where “2” means success and “-2” means failed. Without an ACL, the payment domain gets littered with “decimal.Parse(payhere_amount)” and "statusCode == "2" " checks scattered across business logic.

The “PaymentConfirmedEventHandler” in the application layer works with "PaymentStatus.Success", not “2”. A developer reading that code six months later understands it immediately without opening PayHere documentation.

When PayHere updates their API and changes “2” to “SUCCESS”, one switch statement in "PayHerePaymentAdapter" changes. Nothing else breaks.

The Fourth Crisis: Your Own Microservices

A year later, the platform splits into microservices. The Order Service built with ASP.NET Core, MediatR, and EF Core needs customer data from the Customer Service owned by a different internal team.

The Customer Service exposes a gRPC endpoint with this Protobuf contract

Even though this is an internal company service, it still speaks a different language than the Order domain. Unix timestamps instead of “DateTime”. Loyalty tier as a plain string instead of a proper enum. gRPC generated C# classes instead of domain value objects.

Without an ACL, the gRPC generated classes flow directly into the Order domain. One day, the Customer team splits “full_name” into “first_name” and “last_name”. The Order Service breaks at compile time.

The same discipline is applied. An interface for the Adapter. A Gateway for communication. An Adapter for translation.

When the Customer team splits “full_name” into “first_name" and “last_name”, one line changes in “CustomerServiceAdapter”. The Order domain never knew anything changed next door.

What the .NET Team Learned

At the year-end retrospective, someone put up a slide showing every integration incident from the past year. The NAV upgrade. The inventory service refactor. The PayHere API change. The Customer Service Protobuf change.

Every single incident was absorbed at the ACL boundary. Not one of them touched the domain. Not one of them required changes to the application services, MediatR handlers, or EF Core entities.

The senior developer who built the first NAV adapter summarised it perfectly.

“The Anti-Corruption Layer is not just about where you put the code. It is about understanding what each piece of code actually does and being honest enough to name it accordingly. The few hours it takes to write a proper adapter is the cheapest insurance policy your codebase will ever buy.”

And every developer in that room who had once said, “It’s just a few fields, we don’t need a whole adapter class for this”, nodded quietly and said nothing.

Because they had all seen, at least once, what happens when you let the outside world walk in without a translator at the gate.