Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Anti-Corruption Layer

How a translation layer at the edge of your context keeps a foreign or legacy model out of your domain, in both directions when you write back, and what it costs to own.

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.

The seam, both ways

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, WO and CMNTS become assetId, jobId and notes. The easy part, and the only one a simple renaming handles.
  • Codes and enums. PRI 0 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 6 is inches and PRES 87 is psi; the app's Pipe holds 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/0012 is 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 CL reads 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's completed, it would drop unrepaired jobs from the crews' queue, so the translator keeps CL as a billing fact and treats a job as completed only when its status is WC, work complete.
  • Missing and overloaded data. DUE 1900-01-01 is how the old system says "no due date", and it becomes an empty due date, not a date in the distant past. CMNTS carries the crew lead's name in a convention some dispatchers follow; the translator reads LEAD: 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.

Watch outA layer that passes the legacy system's codes and meanings straight through, so your domain still depends on their types, is a wrapper, not an ACL: the next change on their side still breaks your domain, because your domain still speaks their language.

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.

Practice this