Scaled up to whole-system boundaries, the Adapter pattern reappears as hexagonal architecture's "ports and adapters" and DDD's anti-corruption layer. What changes at that scale, and how do you decide how many adapters and how thick to make them?

## From class-level pattern to architectural style The GoF Adapter reconciles two *classes*. Hexagonal architecture (Alistair Cockburn's *Ports and Adapters*) applies the same idea to a *system boundary*: the application core defines **ports** — interfaces expressing what it needs or offers — and **adapters** connect those ports to concrete technology (HTTP controllers, message consumers, SQL, vendor SDKs, file systems, clocks). *Driving* (primary/inbound) adapters call into the core through inbound ports; *driven* (secondary/outbound) adapters are called by the core through outbound ports. Onion/Clean architecture say the same thing with different vocabulary. Eric Evans' **anti-corruption layer (ACL)** is the DDD framing: when integrating with a system whose model differs from yours (a legacy monolith, a partner API, another team's bounded context), insert a translation layer so *their* model does not leak into *your* ubiquitous language. An ACL is an adapter whose unit of translation is the *domain model*, not the method signature. ## What genuinely changes at scale ### 1. Ownership and direction of dependency At class scale, the target may be someone else's interface. At system scale, the port **must** be defined by the consumer — that is the whole mechanism of dependency inversion. Enforce it structurally: separate modules/packages, with a build-level or ArchUnit-style rule that `domain` may not reference `adapter-*` or any vendor package. If your "port" is just the SDK's interface copied, you have added a file and inverted nothing. ### 2. Translation of models, not calls The hard work is conceptual: their `customer_id` vs your `CustomerId`; their 14 order statuses vs your 4; their eventual consistency vs your read-your-writes expectation; their partial-failure/batch semantics; their pagination and rate limits; their notion of "deleted". The adapter owns all of it, including the judgement calls, and those judgements deserve tests and documentation. ### 3. Failure and time become first-class Every outbound adapter is a network boundary: timeouts, retries (only for idempotent operations), circuit breaking, bulkheads (a bounded pool per dependency so one slow vendor can't consume all threads), and clock/idempotency-key handling. Decide deliberately whether these live *in* the adapter or in a decorator over the port. Decorator placement is usually better: policy is reusable across adapters and testable without any vendor. ### 4. Verification - **Port contract tests**: one abstract suite encoding the port's promises (ordering, absence semantics, error classification, idempotency), executed against every adapter *and* the in-memory fake used by domain tests. This is what stops the fake and the real adapter from drifting — the single most common integration bug. - **Consumer-driven contract tests / recorded interactions** for the wire format against the actual provider. - **Fault-injection tests** for timeout/5xx/partial-response paths, which are otherwise never exercised. ### 5. Observability Span/metric per adapter with the dependency named, error-classification counters (including an "unmapped provider error" counter that must stay at zero), and payload-shape logging that respects the secrets rules. Without this, boundary translation defects are invisible until they're incidents. ## Sizing decisions **How many ports?** Not one per external system reflexively. Group by *capability the domain needs* (`PaymentAuthorizer`, `AddressVerifier`), not by vendor. If two capabilities have different consumers and change rates, two ports. **Canonical model vs point-to-point.** With N sources and M consumers, direct mappings trend toward N×M translators; a canonical internal model makes it N+M. The catch is that a canonical model is a design commitment: it must be owned, versioned, and rich enough not to lose information, or it becomes a lossy lowest common denominator that all adapters fight. Rule of thumb: adopt a canonical port when N and M are both >2 *and* the concepts genuinely overlap. **One generic port or several specific ones?** A port designed for "any payment provider" degrades to the intersection of every provider's features, and you lose the one differentiating capability you actually bought. Sometimes the honest design is a narrow shared port for the common path plus provider-specific capabilities exposed explicitly (optional sub-interfaces), rather than pretending uniformity. **Thick or thin?** Thin adapters (mapping + error translation) are easiest to test and swap. Thickness creeps in via caching, batching, retry, rate limiting and stitching multiple provider calls into one port call. Stitching is often legitimate (the port speaks your language, the provider needs three calls); cross-cutting policy usually is not. **When *not* to abstract.** A single vendor with no realistic replacement, deeply embedded (an ORM, a cloud primitive) may not deserve a port — the abstraction cost is paid forever, the swap never happens, and the abstraction leaks anyway. Judge by blast radius: how many places would a change touch, and how likely is it? Ports also pay for themselves in *testability* alone, which is often the stronger argument than swappability. **Versioning.** Adding a method to a port breaks every adapter; deleting one breaks clients. Treat ports as published interfaces: additive change via new optional interfaces, deprecation windows, and a fake maintained in lockstep. ## Organizational angle Adapters are where team boundaries meet. An ACL is often the artifact that lets a team stop being blocked by another team's model or release cadence — a Conway's-law countermeasure. It also localizes the cost of a partner's breaking change to one module owned by one team, which is a scheduling and risk argument as much as a design one.