Designing a Multi-Provider Integration Layer

Status: outline. Each section below is a prompt to be answered from real experience — replace with what was actually built, tried, or learned.

The problem

• What was the application trying to send or fetch, and through which kind of external provider?
• Why did a single hard-coded provider eventually become a limitation?

The constraints

• What did reliability look like for this system — what happens when a provider is slow, down, or changes behaviour?
• What were the limits: cost, delivery time, team size, existing code?

The architecture

• Where does the abstraction sit — behind one interface, with provider-specific adapters below it?
• How does the application choose a provider, and what happens when the preferred one fails?

application → integration layer → provider adapter → external API
                     ↓
              retries · timeouts · fallback

The engineering decisions

• Chosen: what was the interface actually shaped like?
• Considered: what were the alternatives (direct calls, a vendor SDK, a queue in front)?
• Why: what made this the better fit for the constraints?

The challenges

• What behaved differently between providers — response shapes, error codes, rate limits, delivery receipts?
• What broke in testing that the design had not predicted?

The outcome

• What works now? What became easier to change?
• What would be measured differently next time?

The next iteration

• If this were rebuilt today, what would change?
• What is still a known limitation?