API Gateway ve Dış Entegrasyonlar (API & Integration Architecture)

Bu doküman, Humindx platformunun dış dünyadan (B2C mobil uygulaması, B2B paneli ve 3. parti API müşterileri) gelen trafiği nasıl yönettiğini, yetkilendirme (Auth) sınırlarını ve veri akış güvenliğini tanımlar.

Kapsam Uyarısı: Bu doküman, ağ trafiği yönlendirmesi, API lisanslama (B2B2C), rate limiting ve Webhook bildirimlerini kapsar. Multi-tenant B2B izolasyon mantığı için b2b-tenant-os.md, veri strip/filtreleme prensipleri için ../architecture/system-overview.md dosyalarına bakınız.

---

1. Mimari Rol ve Trafik Ayrıştırma (Traffic Routing)

API Gateway, Humindx ekosisteminin "Sınır Güvenlik Duvarı" ve ana yönlendiricisidir. Gelen trafik, kaynağına ve protokolüne göre üç ana kanala ayrıştırılır:

Kanal / Namespace	Protokol	İstemci Türü	Ana İşlev	Kimlik Doğrulama
/api/v1/b2c/*	WSS / HTTPS	Mobil Uygulama	Sisli Sohbetler, Profil güncellemeleri, DNA görüntüleme.	JWT (User Token)
/api/v1/b2b/*	HTTPS	Kurumsal İK Paneli	Takım analizleri, İşe Alım sorguları, Yönetim Reçeteleri.	JWT (Tenant + Role Token)
/api/v1/partner/*	HTTPS	API Lisans Müşterileri	OAuth2 entegrasyonu, 3. parti uyum eşleştirmeleri.	M2M (API Key + User OAuth)

Tasarım Kararı: WebSocket (WSS) trafiği B2C kanalında sonlandırılır. Gateway, WebSocket mesajlarını alır ve iç ağdaki (Internal) Kafka/Redis Streams'e CHAT_MESSAGE olayı (event) olarak asenkron aktarır.

---

2. API Lisanslama (B2B2C) ve "Sign-in with Humindx"

İş modelinin %15'ini oluşturan API Lisanslama, 3. parti platformların (Örn: Flört uygulamaları, freelancer pazar yerleri) Humindx'in psikometrik motorunu kullanmasını sağlar.

Bu akış, güvenli bir OAuth2.0 + OpenID Connect standardı ile yürütülür:

1. İzin Talebi: Kullanıcı, 3. parti flört uygulamasında "Humindx ile Uyum Skorumu Bağla" butonuna basar.
2. Consent (Rıza) Ekranı: Kullanıcı Humindx ekranına yönlendirilir: "Tinder, senin Sosyal Odan'daki temel Uyum Skorlarına erişmek istiyor. İzin veriyor musun?"
3. Kapsamlı Token (Scoped JWT): Onay verilirse, API Gateway 3. parti uygulamaya sadece read:social_fit_score kapsamına (scope) sahip bir Access Token döner.
4. Bu sayede partner uygulama, kullanıcının ham verilerini veya Profesyonel/Klinik odasını asla sorgulayamaz.

---

3. Webhook ve Olay Bildirim Sistemi (Event Notifications)

Partner uygulamaların sürekli GET /api/v1/partner/users/{id} isteği atması (Polling), hem Humindx altyapısına gereksiz yük bindirir hem de anlık gerçekliği yansıtmaz. Bunun yerine Push-based Webhook Mimarisi kullanılır.

Partner şirketler, Humindx geliştirici portalından kendi Webhook URL'lerini kaydederler. Sistemde kritik bir durum değiştiğinde, API Gateway partnerin URL'sine güvenli bir POST isteği atar (Payload imzalama — HMAC SHA256 ile).

Kritik Webhook Olayları (Event Types):

Event	Tetikleyici	Partner Aksiyonu
consent.revoked	Kullanıcı, 3. partiye verdiği izni iptal eder.	Kullanıcının profilindeki Humindx rozetini anında düşürür.
profile.updated.major	Kullanıcının profilinde majör algoritmik değişim (Örn: bir trait son 3 ayda 10+ puan kaydı).	Eşleştirme algoritmasını yeniden çalıştırabilir.
account.deleted	GDPR kapsamında kullanıcı Humindx hesabını tamamen siler.	Elindeki cache'lenmiş Humindx verisini imha etmek zorundadır.

Güvence Mekanizması: Webhook istekleri başarısız olursa (Partnerin sunucusu çökerse), Exponential Backoff (üstel gecikme) algoritmasıyla 24 saate kadar yeniden denenir (Retry mekanizması).

---

4. Yetkilendirme ve "Consent Engine" (Strip Mekanizması)

Gateway'in en hayati görevi, backend'den çıkan veriyi dış dünyaya iletmeden önce Kullanıcı Rızası (Consent) süzgecinden geçirmektir.

1. B2B paneli GET /candidates/user_84/profile isteği atar.
2. İç servisler (Microservices) adayın tüm özelliklerini Gateway'e iletir.
3. Gateway, consent_grants tablosundan (veya hızlı Redis Cache'inden) adayın Acme Corp (Tenant 101) için izin seviyesinin Level 1 olduğunu görür.
4. Gateway, payload'daki management_recipe, detailed_traits gibi Level 2 ve Level 3 alanlarını siler (Strip eder).
5. B2B paneline sadece izin verilmiş saf JSON iletilir.

Sonuç: İç servislerde yanlışlıkla fazla veri çekilse bile, Gateway son çıkış kapısında veriyi tıraşlayarak güvenliği garanti altına alır.

---

5. Rate Limiting ve Kötüye Kullanım (Abuse) Koruması

Humindx verileri oldukça değerlidir. Kötü niyetli aktörlerin API üzerinden kullanıcıların kişilik verilerini kazımasını (Scraping) veya sistemi manipüle etmesini engellemek için Token Bucket algoritması ile çok katmanlı sınırlandırmalar (Throttling) uygulanır.

Hedef Kitle	Limit Tipi	Kısıtlama Kuralı	Gerekçe
B2C (Mobil)	Etkileşim Limiti	IP/User başına saatte max 50 Chat mesajı.	Bot ağlarının Sisli Sohbetleri manipüle etmesini ve LLM API maliyetlerini patlatmasını önlemek.
B2C (Mobil)	Auth Limiti	Dakikada max 3 Login denemesi.	Brute-force saldırılarını durdurmak.
B2B (Kurumsal)	Sorgu Limiti	Dakikada max 100 rapor çekimi.	Bir İK uzmanı veya ATS entegrasyonu için yeterli, tüm veritabanını indirmek için (Scraping) yetersizdir.
B2B2C (API)	Partner Kotası	Lisans anlaşmasına bağlıdır (Örn: Saniyede 500 istek / 500 TPS).	Tier bazlı faturalandırma (Billing) için SLA (Service Level Agreement) sınırlarını belirler.

---

Son Güncelleme: 2026-04-15 — Gateway yönlendirmesi, OAuth2 API lisanslama, Webhook mimarisi, Consent Strip filtrelemesi ve Rate Limiting sınırları tanımlandı.