Context Mapping & the Anti-Corruption Layer

Lesson 7 of the DDD course · Translating between contexts — especially the ones you don't control · ~30 minutes

1 · Value objects 2 · Entities & identity 3 · Aggregates 4 · Lifecycle state machines 5 · Domain events 6 · Bounded contexts 7 · Context mapping 8 · Functional core 9 · Capstone
Why this matters for your mission Your startup will integrate with Stripe, tax APIs, logistics providers — systems whose models you don't control and can't change. The anti-corruption layer is how you take their data without letting their worldview rewrite yours.

Contexts are separate on purpose — but they must exchange facts. Today: the vocabulary for how contexts relate, and deep practice on the one relationship every startup gets burned by.

1 · The context map

A context map is exactly what it sounds like: your contexts, drawn, with the relationships between them named. The patterns have deliciously blunt names — and each is a decision about who adapts to whom.[Evans]

PatternWho adaptsWhen it's right
Shared kernelboth, on a small joint modeltwo contexts you control, tightly coupled needs — keep the shared slice tiny
Customer–supplierupstream serves downstream's asksyou control both ends and upstream prioritizes downstream
Conformistyou adopt the upstream model as-isupstream won't change, their model is fine, translation isn't worth it
Anti-corruption layer (ACL)you translate at the boundaryupstream's model is foreign or hostile to yours — most external vendors
Published languageboth speak a documented common modelmany integrations around one standard

Meridian's map, drawn honestly: ordering is customer–supplier with billing (both yours); ordering is ACL with BigPay, the external payment provider (theirs, forever); shipping conforms to the carrier's label API because translating it isn't worth it. Three relationships, three deliberate choices — not one accidental tangle.

2 · The layer that saves your model

An anti-corruption layer is a boundary adapter with one job: foreign concepts enter only after translation into your model, in exactly one place.[Evans] Without it, watch what happens: BigPay sends amount as a string of cents and a status enum ("succeeded"); someone stores it raw; a month later Billing types have fields like bigpay_status; the vendor's vocabulary — their decisions — now shapes your domain. That's the corruption.

The shape of the medicine, in our style — one file, pure functions:

// src/shell/bigpay-acl.ts — the ONLY file that knows BigPay's shape

interface BigPayWebhook {          // their model: snake_case, string cents
  event: string;                   // "payment.succeeded"
  amount: string;                  // "1250"
  currency: string;                // "usd"
  reference: string;               // our orderId
}

export function toPaymentCaptured(w: BigPayWebhook): Result<PaymentCaptured, AclError> {
  if (w.event !== "payment.succeeded")
    return { ok: false, error: "unknown payment event" };
  const cents = Number(w.amount);
  if (!Number.isInteger(cents) || cents < 0)
    return { ok: false, error: "invalid amount from provider" };
  return { ok: true, value: { type: "PaymentCaptured", orderId: w.reference,
                              amountCents: cents, currency: w.currency.toUpperCase() } };
}

Notice this is Lesson 1 all over again — parse, don't validate — applied at a context boundary instead of a string boundary. The foreign payload is untrusted input; the output is a proven value in your language. Everything downstream consumes PaymentCaptured and cannot spell “BigPay”.

The rules (1) One adapter module per foreign system — greppable, mockable, deletable. (2) Translation is tested by pinning: their real webhook shape → your expected model. (3) Unknown foreign values become typed errors, never silent guesses — a vendor adding a new status should make noise in your logs, not corrupt your data.
Gotchas (1) ACL effort scales with how central the vendor is: full ACL for your payment provider, maybe mere conformism for a one-off geocoder. (2) Don't ACL your own contexts by reflex — between two models you control, customer–supplier with a tiny shared kernel of ids is cheaper. (3) If the adapter file grows conditionals per-endpoint, the vendor's complexity is leaking — consider wrapping their operations too, not just their data.

3 · Practice: build the ACL

4 · Retrieval check

5 · Where this goes next

Contexts translate at their edges. One boundary remains unexamined: the database. Next lesson ties the whole course together with functional core, imperative shell — where I/O lives, and why your repository is just another parser.

Your teacher is the agent Before touching a third-party API in your product, sketch its ACL with me: hand me the ugliest webhook they send and we'll design the translation and its error cases together.
Primary source for this lesson Read the context-mapping chapters of Khononov's *Learning Domain-Driven Design* for modern guidance, then Evans' original patterns chapter in the Blue Book for the source definitions. King's “Parse, don't validate” is the translation philosophy.
← Lesson 6: Bounded contexts Patterns cheat sheet →