pattern

Model Translation Boundary

The layer at which an external system's model is converted into your own, preventing its concepts and accidents from spreading into your domain.

Every integration presents a choice: adopt the other system's model, or translate at the boundary. Adopting it is cheaper today and means that forty years of the other system's naming, encodings, status codes and historical oddities become permanent features of your domain.

The translation boundary keeps the foreign model contained. Inside it, your domain uses concepts your business recognises; outside it, the external system is unchanged.

Where it is essential: legacy integration, where the source model is fixed and archaic; CDC feeds, which carry raw table and column names and must never become a published contract; B2B integration, where the partner's format is not negotiable; and vendor SDKs, where the vendor's abstractions leak into your code by default.

Design points that decide whether it works:

Ownership belongs to the side that changes less predictably — usually the side integrating with the fixed system — so the cost of adaptation falls where the change originates.

Translation must be total. A boundary that passes some foreign concepts through unchanged, "just for now", is not a boundary — and the exceptions are what eventually make the migration away from the legacy system impossible.

The cost is real: an extra layer, extra mapping code, and a place where bugs hide. It is worth paying where the external model is durable and foreign, and not worth paying for a well-designed API that already speaks your language.