Skip to content
Ikamet OS Docs

Provider Philosophy

The rule

Frontends never call providers directly. All provider interactions are routed through app-api and the provider adapter layer.

See Provider Adapter Layer for the technical architecture.

Provider categories

CategoryProviders
InsuranceQuick Sigorta, Hepiyi Sigorta, Sompo, Türk Nippon, Doğa, EMAA, Arex, Ankara Sigorta
MessagingWhatsApp Cloud API (Meta), SendGrid, Twilio
PaymentsStripe, Wise
GovernmentImmigration (e-Government), Land Registry, Ministry of Labour
SecurityFingerprintJS, Cloudflare WAF, Cloudflare Turnstile, Stripe Radar
AIOpenAI, Claude (Anthropic)

Provider selection philosophy

Insurance

Ikamet is a broker, not an insurer. This means:

  • We access multiple insurers for each product type
  • The customer gets the best available quote, not a single provider’s offer
  • We are not tied to any single insurer’s technology or pricing
  • Commission structure varies by provider — this is tracked separately from the operational system

Messaging

WhatsApp is the primary channel. Email and SMS are secondary. Selection criteria:

  • WhatsApp — primary for all customer communications; highest open rates
  • Email — policy documents, formal confirmations, documents that need a paper trail
  • SMS — OTP / verification only via Twilio Verify; fallback for non-WhatsApp users

Payments

  • Stripe — primary payment processor; used for card payments, subscriptions, invoicing
  • Wise — international transfers; used for cross-border payments from non-Turkish accounts

Provider failure handling

Providers go down. The adapter layer must:

  • Return clear errors to the API (not bubble up raw provider errors to the frontend)
  • Log all provider failures to the timeline where relevant
  • Support retry logic for transient failures
  • Support fallback to alternative providers where possible (e.g., if one insurer API is down, try next)

Adding a new provider

  1. Create an adapter module in app-api/src/adapters/{category}/{provider-name}.adapter.ts
  2. Implement the category interface (e.g., InsuranceProviderAdapter)
  3. Add the provider to the category’s index.ts (unified interface)
  4. Add credentials to environment variables — never hardcode
  5. Document the provider’s quirks in /providers/{category} in this docs site
  6. Test in staging before enabling in production