# Integration Design

Integration discipline for third-party APIs and service boundaries.

## Rules

1. **Treat external APIs as unreliable.** They will timeout, rate-limit, return errors, and change without warning. Wrap every call with timeout, retry policy, and graceful degradation.

2. **Isolate vendor specifics behind your boundary.** Your domain code calls your adapter, not Stripe/SendGrid/Twilio directly. When the vendor changes, you change one file.

3. **Webhook handlers verify signatures.** If you accept webhooks without cryptographic verification, anyone on the internet can trigger your business logic.

4. **Map external errors to internal semantics.** "Stripe returned 402" is not a user-facing message. Translate vendor errors into your domain's error vocabulary at the boundary.

5. **Contract tests for integrations.** When the third party changes their API, you find out in CI, not in production. Record fixtures or use sandbox environments.

6. **Document the failure modes.** What happens when this API is down? What data is lost? What's the manual fallback? An integration without a failure plan is a future incident.

## What This Replaces

Direct vendor SDK calls scattered through business logic, unverified webhooks, and integrations that work in the happy path and fail silently everywhere else.