The Anti-Corruption Layer
The mainframe's worldview stops at the border.
The incident
The new platform launched clean: modern stack, clean domain model, good tests. It integrated directly with the legacy SOAP services because a translation layer felt like ceremony. Within a year, the clean domain model had a field called CUST_FLAG_7, three date formats, and null semantics from 1997 — the legacy system had quietly colonized its replacement.
Why the obvious approach fails
Direct integration with a legacy system imports more than data — it imports assumptions. Legacy formats, magic values, and implicit rules leak into the new domain model one 'temporary' accommodation at a time, until the new system is shaped like the old one with better syntax. The corruption is gradual and each step looks pragmatic, which is exactly why it needs a structural defense: one boundary layer that speaks legacy on one side and the clean model on the other, where every translation, workaround, and semantic mismatch is contained, documented, and — when the legacy system finally dies — deletable in one place.
The standard
- All communication with legacy systems passes through a dedicated translation layer; direct calls from modern business logic are banned.
- The layer owns both dialects: legacy formats and semantics on one side, the clean domain model on the other — and the clean side never learns legacy vocabulary.
- Semantic mismatches (magic values, implicit rules, encoding quirks) are resolved inside the layer, explicitly and documented — never patched in domain code.
- The layer's translations are contract-tested against recorded legacy behavior, so a quiet legacy change is caught at the border.
- The layer is built to be deleted: when the legacy system retires, the modern codebase loses an adapter, not its shape.
How Cortex validates it
At plan time
integration blueprints map every legacy touchpoint to the layer and document each known semantic mismatch as a translation rule.
At validation
assert: legacy_calls outside acl == 0assert: domain_model.contains(legacy_vocabulary) == falseassert: translations.contract_tested against recorded_behaviorAssertion syntax is illustrative.
At review
the approver sees the border audit: every legacy touchpoint routed through the layer, and the domain model's vocabulary clean on inspection.