Provider Portability Boundary

Architecture note

This page is about the boundary that preserves choice.

Provider-native services can be valuable, but product behavior should not have to speak every vendor dialect directly.

Core claim

An internal contract layer is useful when it makes tradeoffs explicit and keeps the product from being pinned to one provider’s vocabulary.

Internal contract

Normalize the capabilities the product depends on and decide which guarantees are part of the platform promise.

Adapter layer

Keep provider-specific behavior close to the edge so the product and operating model remain understandable.

Questions for the contract layer

• Which capabilities are first-class enough to belong in the shared contract?
• Which outputs need normalization, and which should remain provider-specific?
• What metrics or failures must flow back out of the adapter layer?
• When is a provider-native escape hatch worth the portability cost?

A portability layer should not pretend differences disappear.

If one provider has better latency, different safety controls, or a unique tool interface, capture that honestly instead of hiding it behind vague abstraction language.