A record in someone else's words
One work order, exactly as a regional water utility's asset-management system returns it: WO 0047113 | AST DIST-04/0012 | PRI 2 | STAT CL | DIAM 6 | PRES 87 | DUE 1900-01-01 | CMNTS LEAD:R.OKAFOR CALL FIRST.
The system is decades old and is still the record of every pipe, valve and hydrant the utility owns, and of every job done on them. The utility is building a new field-service app for its repair crews, and the app's team has its own model, built for that work. A Job has an urgency, a location and a crew lead. A Pipe has a diameter in millimetres and an operating pressure in bar. None of those words appears in the record above.
Their codes, everywhere
The first version of the app read the legacy fields directly. Scheduling code checked wo.STAT === "CL", the map converted DIAM from inches wherever it drew a pipe, and the queue sorted jobs by PRI with 1 at the top, because 1 was the most urgent code. Within a few months, the old system's vocabulary was spread across forty files of the new app.
Then the asset team added priority 0 for burst mains. The old system's own screens handled it, so the change went out without a word to the app's team. The app's sort had no case for 0 and treated any priority it did not know as routine, so the next burst main went to the bottom of the queue. The fix was one line. Finding every other place that compared priorities took a week, with no way to be sure they had all been found.
One place where their words become yours
An Anti-Corruption Layer (ACL) sits between your context and an external or legacy system and translates between their model and yours (both ways when you also write to them), so the foreign vocabulary and quirks stay out of your domain. In the rebuilt app, scheduling code asks for the open jobs for a crew and gets Job objects back. Only the ACL knows that the asset system exists, how to call it, and what PRI 2 means.
The layer belongs to the side that needs protecting, and it lives at the edge of that side's Bounded Context: the asset team changes nothing and does not need to know it is there.
Work order rows come in and leave the ACL as Jobs; a finished Job goes back out as the asset system's own codes. The field-work code never calls the asset system directly.
Structurally, it is Adapter at strategic scale: usually a Facade over the foreign system plus Adapters and translators that map its concepts into your model. Here the facade turns the three requests behind one job (the work order, its asset and its crew) into one call, and each translator owns one mapping, so a change on the other side has one place to land. The building blocks have their own articles, Facade and Adapter.
What a translator actually translates
Back to the record at the top: nearly every field needs a different kind of translation.
- Names.
AST,WOandCMNTSbecomeassetId,jobIdand notes. The easy part, and the only one a simple renaming handles. - Codes and enums.
PRI0 to 4 becomes the app's urgency: emergency, urgent or planned. The translator lists every code it knows, and an unknown code is an error someone sees, not a quiet default. That is the real fix for the burst main: a new code can no longer pass as routine unnoticed. - Units.
DIAM 6is inches andPRES 87is psi; the app'sPipeholds about 152 mm and 6.0 bar. Converted once, at the edge, no number inside the app leaves anyone guessing its unit. - Identity.
DIST-04/0012is a district code plus a sequence number, and the asset system renumbers assets when districts are redrawn. The ACL keeps a table from legacy keys to the app's own stable ids, updated from the old-to-new key list that comes with each renumbering, so a redrawn district does not cut a pipe off from its repair history. - Meaning.
STAT CLreads like "closed", but in the asset system it means closed for billing, which finance can set as soon as a job's cost is approved, before any crew has done the work. Mapped to the word that looks closest, the app'scompleted, it would drop unrepaired jobs from the crews' queue, so the translator keepsCLas a billing fact and treats a job as completed only when its status isWC, work complete. - Missing and overloaded data.
DUE 1900-01-01is how the old system says "no due date", and it becomes an empty due date, not a date in the distant past.CMNTScarries the crew lead's name in a convention some dispatchers follow; the translator readsLEAD:when it is there and leaves the crew lead empty when it is not, instead of guessing.
Writing back
Reading is half the job. When a crew finishes a repair, the app records the Job as done with the pressure they measured, and the asset system has to hear it in its own terms: the legacy key, the pressure back in psi, and status WC, work complete, because CL is finance's to set. That outbound mapping is a second translator with its own tests, and it translates failures too: an ERR 41 from the asset system reaches the app as an error in the app's own terms.
What it costs to own
An ACL is code your team writes and keeps. Learning the mapping, for a system this old, means reading its documentation, its data and sometimes its source to find out what a code really means. The mapping then drifts: when the other side changes, as it did with priority 0, it is wrong until someone notices, and it breaks in one place instead of forty files, but it still breaks. The unknown-code error above catches a code that did not exist before. Translation tests built from real records, run on every change and given fresh records from each foreign release, show where a release sends data in a shape the mapping no longer handles; for a field that maps both ways without loss, translating a record in and back out and comparing adds a cheap check. A change of meaning in a known code or field, such as a new unit in the same format, can pass all of these, especially while the tests' expected results still encode the old reading. It usually surfaces through the other side's release notes or its team, and those can be incomplete; once it is confirmed, the mapping and the tests' expected results change together.
For a small, stable upstream model already close to yours, all that work can cost more than it saves; whether to adopt their model as it is instead is the decision Conformist is about.
Build the seam in the Challenge
The Anti-Corruption Layer Challenge asks for this seam: your context, the legacy system and the layer between them. This Challenge's palette has no External System node, so a Service stands in for the legacy side, as in the diagram above. Focus on one thing: your domain depends only on the ACL, and the foreign model is translated on the way in. Label the edge into the ACL in their vocabulary and the edge out of it in yours, so the Grid shows which of their concepts become which of yours. A good run has your domain code referencing only your own model's vocabulary.