Provider Adapter Layer

The rule

Frontend applications never call provider APIs directly. All provider interactions go through app-api.

Customer (browser)
        ↓
   app-web / app-admin
        ↓
     app-api
        ↓
  Provider Adapter Layer
        ↓
  Provider APIs (insurers, government systems, payment gateways)

Why

Provider switching — if an insurer changes their API, only the adapter changes; no frontend code changes
Credential security — provider API keys never touch the frontend
Normalization — each provider returns data in different formats; the adapter normalizes to a consistent internal schema
Rate limiting — the adapter can queue, retry, and throttle provider calls
Logging — all provider interactions are logged in one place

Adapter structure

Each provider gets its own adapter module in app-api/src/adapters/:

adapters/
├── insurance/
│   ├── quick-sigorta.adapter.ts
│   ├── hepiyi-sigorta.adapter.ts
│   ├── sompo.adapter.ts
│   └── index.ts           ← unified interface
├── government/
│   ├── immigration.adapter.ts
│   └── index.ts
└── payments/
    ├── stripe.adapter.ts
    └── wise.adapter.ts

Adapter contract

Every insurance adapter implements the same interface:

interface InsuranceProviderAdapter {
  getQuote(params: QuoteParams): Promise<Quote[]>
  issuePolicy(params: PolicyParams): Promise<IssuedPolicy>
  cancelPolicy(policyId: string): Promise<void>
  renewPolicy(policyId: string, params: RenewalParams): Promise<IssuedPolicy>
}

Frontend code calls:

// app-api route handler
const quotes = await insuranceAdapter.getQuote(params);
// adapter internally calls the right provider

Never:

// ❌ NEVER — direct provider call from frontend or route without adapter
const quotes = await fetch('https://api.quicksigorta.com/quotes', { ... });

Current provider integrations

Provider	Category	Status
Quick Sigorta	Insurance	Planned
Hepiyi Sigorta	Insurance	Planned
Sompo Sigorta	Insurance	Planned
Türk Nippon Sigorta	Insurance	Planned
Doğa Sigorta	Insurance	Planned
EMAA	Insurance	Planned
Arex Sigorta	Insurance	Planned
Ankara Sigorta	Insurance	Planned
Stripe	Payments	Active
Wise	Payments	Planned
WhatsApp Cloud API	Messaging	Active
SendGrid	Email	Active
Twilio	SMS / Verify	Active