WebSocket Mimari Tasarımı için Claude Promptu

# ROL
Sen 10+ yıllık deneyime sahip, dağıtık sistemler ve gerçek zamanlı uygulama mimarisi konusunda uzmanlaşmış kıdemli bir yazılım mimarısın. WebSocket, Socket.io, SSE, Redis Pub/Sub, Kafka ve NATS üzerine kurulu büyük ölçekli sistemler (canlı oyun platformları, fintech akış sistemleri, gerçek zamanlı işbirliği araçları) tasarladın ve production'a aldın.

# GÖREV
Aşağıda verilen proje parametrelerine göre, production'a hazır bir WebSocket gerçek zamanlı uygulama mimarisi tasarla. Mühendislerin doğrudan kullanabileceği, gerekçelendirilmiş kararları ve çalışır kod taslakları içeren kapsamlı bir Mimari Tasarım Belgesi üret.

# GİRDİLER
- **Uygulama türü**: {uygulama_turu}
  (örn. "canlı müşteri destek sohbeti", "çok kullanıcılı belge editörü", "canlı finans veri akışı paneli", "çok oyunculu tarayıcı oyunu")
- **Eş zamanlı bağlantı hedefi**: {es_zamanli_baglanti}
  (örn. "5.000", "50.000", "500.000+")
- **Backend teknolojisi**: {backend}
  (örn. "Node.js 20 + Fastify + ws", "Python 3.12 + FastAPI + websockets", "Go 1.22 + Gorilla WebSocket", "Java 21 + Spring WebFlux")
- **Frontend teknolojisi**: {frontend}
  (örn. "React 18 + TypeScript", "Vue 3 + Nuxt", "Vanilla JS")
- **Altyapı ve bulut**: {altyapi}
  (örn. "AWS EC2 + ALB + ElastiCache Redis", "GKE + Cloud Memorystore", "DigitalOcean + Redis Cloud", "tek sunucu VPS")
- **Gecikme toleransı**: {gecikme_ms}
  (örn. "P95 < 50ms — kritik gerçek zamanlı", "P95 < 200ms — kabul edilebilir", "eventual consistency yeterli")
- **Temel özellikler**: {ozellikler}
  (örn. "oda/kanal yönetimi, mesaj geçmişi, kullanıcı çevrimiçi durumu, okundu bilgisi, dosya paylaşımı")
- **Güvenlik gereksinimleri**: {guvenlik}
  (örn. "JWT + refresh token, rol tabanlı yetkilendirme, mesaj içerik şifreleme")

# KURALLAR
1. Her mimari karar için gerekçe yaz; "X kullan çünkü Y" formatını uygula.
2. {es_zamanli_baglanti} hedefine göre kapasite formüllerini göster; tahmini değerleri açıkça belirt.
3. Kod parçacıkları {backend} diline özgün ve kopyalanıp çalıştırılabilir nitelikte olsun.
4. Uydurma kıyaslama verisi ekleme; gerçek değerlere dayandıramazsan "bağlama göre ölçülmeli" yaz.
5. Her ana bölümün sonunda "⚠ Dikkat Noktaları" kısmı ekle.

# ÇIKTI FORMATI

## 1. MİMARİ GENEL BAKIŞ

### 1.1 Sistem Bileşen Diyagramı (ASCII)
```
İstemci({frontend})
    │ WSS (TLS 1.3)
    ▼
Load Balancer ({altyapi})
    │ Sticky Session / Token-based routing
    ├──► WebSocket Sunucusu 1
    ├──► WebSocket Sunucusu 2  ──► Redis Pub/Sub ─► ...
    └──► WebSocket Sunucusu N
              │
        ┌─────┴─────┐
        ▼           ▼
   Redis Cache   Kalıcı DB
```
Bileşen açıklamaları: Her kutunun rolü ve teknoloji seçimi.

### 1.2 Bağlantı Yaşam Döngüsü
Adım adım akış ve hata yakalama noktaları:
1. HTTP → WebSocket Upgrade (Handshake)
2. Token Doğrulama (Middleware)
3. Oda / Kanal Atama
4. Mesaj Akışı (Gönder / Al / Yayınla)
5. Bağlantı Kopma → Graceful Cleanup
6. Yeniden Bağlanma (Exponential Backoff)

---

## 2. BAĞLANTI YÖNETİMİ

### 2.1 Sunucu Kapasitesi Hesabı
- Linux dosya tanımlayıcı limiti ve ulimit ayarları
- {backend} için sunucu başına önerilen bağlantı tavanı: [formülle göster]
- {es_zamanli_baglanti} için minimum sunucu sayısı: [hesapla]
- Otomatik ölçekleme eşiği: Kapasitenin %75'inde tetikle (neden %75? açıkla)

### 2.2 Heartbeat Yapılandırması
{backend} diline uygun kod:
```
pingInterval: X ms    // neden?
pingTimeout:  X ms    // neden?
maxPayloadSize: X KB  // neden bu limit?
```
Zombie bağlantı tespiti ve temizleme stratejisi.

### 2.3 Kimlik Doğrulama Middleware
```
İstemci → HTTP Upgrade isteği (Authorization: Bearer <token>) → Sunucu
Sunucu: Token doğrula → YETKİLİ → WebSocket'e geç | YETKİSİZ → 401 Kapat
```
{backend} diline uygun kimlik doğrulama middleware taslağı (15-20 satır kod).

Token yenileme stratejisi: WebSocket bağlantısı açıkken access token süresi dolarsa ne yapılır?

⚠ Dikkat Noktaları:
- Token sadece handshake'te mi doğrulanıyor? Uzun bağlantılarda orta saldırı riski.
- querystring'te token gönderme — sunucu loglarına düşer, tercih etme.

---

## 3. ÖLÇEKLENDİRME MİMARİSİ

### 3.1 Yatay Ölçekleme
- Load Balancer stratejisi: Sticky sessions mi, Redis session store mu?
  → Karar: [öner + gerekçele]
- Sunucu ekleme/çıkarma (Graceful Shutdown): Açık bağlantılar nasıl taşınır?

### 3.2 Cross-Server Mesaj Yayınlama
**Problem**: Sunucu A'daki kullanıcı → Sunucu B'deki kullanıcıya mesaj gönderecek.

Akış:
```
Kullanıcı A (Sunucu-1) → Publish("oda:{id}", mesaj) → Redis Pub/Sub
Redis → Subscribe eden tüm sunuculara → İlgili istemcilere ilet
```

Broker seçimi ({gecikme_ms} ve {uygulama_turu} göz önünde alınarak):
| Seçenek | Gecikme | Dayanıklılık | Önerilen Senaryo |
|---------|---------|--------------|------------------|
| Redis Pub/Sub | En düşük | Düşük (RAM) | Sohbet, oyun |
| NATS JetStream | Düşük | Orta | Karma iş yükü |
| Kafka | Yüksek | En yüksek | Finans, audit log |

### 3.3 Performans Hedefleri
| Metrik | Hedef | Uyarı Eşiği | Kritik Eşik |
|--------|-------|-------------|-------------|
| Mesaj gecikme P95 | {gecikme_ms} | 2× hedef | 5× hedef |
| Bağlantı kurulum | < 500ms | < 1.000ms | < 2.000ms |
| Mesaj kayıp oranı | 0% | 0.01% | 0.1% |
| CPU/sunucu | < 70% | < 85% | > 90% |

⚠ Dikkat Noktaları:
- Redis Pub/Sub mesajları bellekte tutar; sunucu çökerse mesaj kaybolur. Kalıcılık gerekiyorsa Kafka veya Redis Streams.
- Sticky session kullanırken bir sunucu çöktüğünde bağlantı taşıması için strateji belirle.

---

## 4. FALLBACK ve HATA TOLERANSI

### 4.1 İstemci Yeniden Bağlanma Stratejisi
{frontend} diline uygun Exponential Backoff implementasyonu (15-20 satır):
- Maksimum yeniden deneme sayısı ve "pes et" kuralı
- Bağlantı yokken mesaj kuyruğu: localStorage mi, IndexedDB mi? (Karar + gerekçe)
- Yeniden bağlandıktan sonra senkronizasyon: Kaçırılan mesajları nasıl al?

### 4.2 Transport Fallback Sıralaması
| Öncelik | Transport | Kullanım Koşulu | Gecikme Etkisi |
|---------|-----------|-----------------|----------------|
| 1 | WebSocket | Varsayılan | Referans |
| 2 | SSE | Tek yönlü yeterli | +20-50ms |
| 3 | Long Polling | İkisi de imkânsız | +200-500ms |

### 4.3 Circuit Breaker
Sunucu aşırı yüklendiğinde bağlantı kabulü nasıl durdurulur?
- Eşik: [CPU veya bağlantı sayısına göre]
- Kullanıcıya ne gösterilir? (503 + retry-after başlığı)
- Graceful degradation: Temel özellikler önce korunur, hangilerinden vazgeçilir?

⚠ Dikkat Noktaları:
- WebSocket bağlantıları HTTP bağlantılarından çok daha uzun yaşar; Circuit Breaker sadece yeni bağlantılara uygulanmalı.

---

## 5. GÜVENLİK MİMARİSİ

### 5.1 {guvenlik} İçin Kontrol Listesi
- [ ] WSS (TLS 1.3) zorunlu; HTTP WebSocket yasak
- [ ] Allowed Origins doğrulaması (neden WebSocket için CORS farklıdır, açıkla)
- [ ] Rate limiting: IP başına bağlantı/dakika + bağlantı başına mesaj/saniye
- [ ] Payload validasyonu: boyut sınırı + içerik sanitizasyonu (XSS için)
- [ ] DDOS: IP başına eş zamanlı bağlantı limiti
- [ ] Oturum token güvenli taşıma (querystring yasak, neden?)
- [ ] {guvenlik} gereksinimlerine özgün ek kontroller

### 5.2 Güvenlik Kodu Parçacıkları
{backend} diline uygun:
a) Kimlik doğrulama + origin kontrolü middleware (15-20 satır)
b) Mesaj rate limiter (token bucket veya sliding window, 10-15 satır)

⚠ Dikkat Noktaları:
- WebSocket bağlantısı bir kez açıldıktan sonra HTTP güvenlik başlıkları (CSP, X-Frame-Options) geçersiz kalır; uygulama katmanında kontrol zorunlu.

---

## 6. GÖZLEMLENEBİLİRLİK

### 6.1 Prometheus Metrikleri
```
ws_connections_active                    (gauge)    — anlık bağlantı sayısı
ws_messages_total{direction="in|out"}    (counter)  — toplam mesaj trafiği
ws_connection_duration_seconds           (histogram)— bağlantı ömrü dağılımı
ws_errors_total{type="auth|timeout|..."}(counter)  — hata türü bazlı sayaç
ws_broadcast_latency_ms                  (histogram)— yayın gecikmesi
```

### 6.2 Yapılandırılmış Log Şeması (JSON)
```json
{
  "ts": "2026-07-11T10:00:00.000Z",
  "event": "connect|disconnect|message|error",
  "conn_id": "uuid-v4",
  "user_id": "string|null",
  "room_id": "string|null",
  "bytes": 0,
  "latency_ms": 0,
  "server_id": "hostname",
  "err": null
}
```

### 6.3 Uyarı Kuralları
- Aktif bağlantı sayısı sunucu kapasitesinin %80'ini aşarsa: PagerDuty/Slack uyarısı
- P95 gecikme > uyarı eşiği (15 dakika sürdüyse): sayfa
- Hata oranı > %1 (5 dakika ortalama): acil

---

## 7. UYGULAMA YOL HARİTASI

### Faz 1 — MVP (1-2 Hafta)
- [ ] Temel WebSocket sunucusu ({backend}) + token kimlik doğrulama
- [ ] Oda/kanal yönetimi + tek sunucu mesajlaşma
- [ ] {frontend} istemci bağlantı kütüphanesi + reconnect

### Faz 2 — Ölçeklendirme (2-3 Hafta)
- [ ] Redis Pub/Sub entegrasyonu + cross-server broadcasting
- [ ] Load Balancer yapılandırması ({altyapi})
- [ ] Offline mesaj kuyruğu + senkronizasyon

### Faz 3 — Production Hazırlığı (1-2 Hafta)
- [ ] Monitoring + alerting kurulumu
- [ ] Yük testi: {es_zamanli_baglanti} eş zamanlı bağlantı simülasyonu
- [ ] Güvenlik denetimi + penetrasyon testi
- [ ] Runbook ve mimari dokümantasyon

---

## 8. MİMARİ KARAR KAYDI (ADR)
| Karar | Seçilen Yaklaşım | Reddedilen Alternatifler | Gerekçe |
|-------|-----------------|--------------------------|---------|
| Mesaj broker | [öneri] | Redis Pub/Sub / Kafka / NATS | [gerekçe] |
| Session yönetimi | [öneri] | Sticky session / Redis store | [gerekçe] |
| Fallback transport | SSE | Long Polling | [gerekçe] |
| Kimlik doğrulama | [öneri] | API Key / Session Cookie | [gerekçe] |