Integrate a legacy system through a typed adapter

Legacy integration becomes fragile when old field names and encodings spread through business logic. A typed adapter confines that instability. It translates the source contract into a domain contract, rejects ambiguous values and preserves the raw identifier needed to investigate.

Build the decision artifact

Capture representative payloads, including nulls, sentinel values, duplicate identifiers and unexpected encodings. Define the domain types and invariants independently. Map explicitly, validate before use and version the adapter. Keep transport retries outside mapping logic, and make write operations idempotent at the boundary.

The enterprise delivery lab makes this reasoning executable with synthetic data:

from enterprise_cases import typed_adapter_case

result = typed_adapter_case()
assert result["mapped"] == {"customer_id": 42, "amount": 1250.5, "active": True}
assert result["schema_version"] == "adapter-v1"
assert result["errors"] == []
assert result["legacy_system_contacted"] is False

The lab converts CUST_NO, INV_TOTAL and the Y flag into an integer customer id, numeric amount and boolean. It calls no legacy system; the fixture proves transformation behavior. That boundary lets the rest of the application use stable language while compatibility tests guard the source quirks.

Test the failure path

A permissive adapter that silently coerces every value creates clean-looking corrupt data. Quarantine unknown codes, count mapping failures and attach a safe raw reference. Do not expose credentials or full sensitive payloads in the error returned to an agent or user.

Save evidence that another reviewer can inspect:

• source and domain schemas
• mapping table with invalid-value behavior
• golden payload contract tests
• version and deprecation policy

This exercise aligns with the enterprise delivery, secure integration, operations and leadership work in the FDE for Professionals course. The course link describes the pathway; this local draft and its synthetic verifier do not claim that a client deployment, security approval or production result occurred.

Practice task

Collect ten sanitized legacy payload shapes. Design the domain model first, then write an adapter test for every coercion you allow and reject.

Continue learning

This article is part of the Enterprise AI delivery and architecture sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Enforce document authorization before semantic retrieval.
• Continue with Plan an enterprise connector migration with compatibility tests.

Reference: Martin Fowler: Data Mapper.