ADR-001: Backend Framework Olarak FastAPI Secimi

Durum	Kabul Edildi
Tarih	2025-11
Karar Veren	Güçlü Ceyhan

Baglam

Zeus 2.0, gunes enerjisi santralleri icin gercek zamanli enerji yonetim sistemidir. Backend'in karsilamasi gereken temel gereksinimler:

• Yuksek performansli async API: Yuzlerce cihazdan es zamanli telemetri verisi
• WebSocket destegi: Gercek zamanli dashboard guncellemeleri
• MQTT subscriber: Broker'dan gelen verileri ayni process icinde islemek
• Otomatik API dokumantasyonu: OpenAPI/Swagger
• Tip guvenligi: Request/response validasyonu
• Python ekosistemi: Celery, SQLAlchemy, asyncpg gibi olgun kutuphaneler

Karar

FastAPI 0.115 backend framework olarak secildi.

Alternatifler

Django REST Framework

• Artilari: Olgun ekosistem, admin paneli, ORM
• Eksileri: Sync-first mimari, async destegi sinirli (Django 4.x ile gelismekte), monolitik yapi
• Red nedeni: MQTT subscriber ve WebSocket icin async performans yetersiz

Flask

• Artilari: Hafif, esnek, genis topluluk
• Eksileri: Async destegi ek kutuphane gerektirir (Quart), otomatik dokumantasyon yok, tip validasyonu manuel
• Red nedeni: Modern async ihtiyaclari karsilamak icin cok fazla eklenti gerekli

Express.js (Node.js)

• Artilari: Event-driven, non-blocking I/O, npm ekosistemi
• Eksileri: Python ekosisteminden vazgecmek, tip guvenligi icin TypeScript ek yuk, Celery yerine alternatif gerekli
• Red nedeni: Ekibin Python deneyimi ve Python ekosistemine bagimlilik

Go/Gin

• Artilari: Yuksek performans, dusuk bellek, concurrency
• Eksileri: Daha az olgun ORM'ler, gelistirme hizi Python'dan dusuk, ekipte Go deneyimi sinirli
• Red nedeni: Gelistirme hizi ve ekip yetkinligi

Gerekce

FastAPI su temel avantajlari sundu:

1. Native async/await: asyncio event loop uzerinde MQTT subscriber, WebSocket handler ve HTTP endpoint'ler ayni process'te calisir
2. Otomatik OpenAPI: Endpoint tanimlarindan Swagger UI ve ReDoc otomatik uretilir — frontend ekibi ile entegrasyon kolaylasir
3. Pydantic validasyon: Request/response semaları tip-guvenli, otomatik validasyon ve serialization
4. MQTT subscriber ile ayni event loop: aiomqtt kutuphanesi FastAPI'nin asyncio loop'u icinde calisir — ayri bir servis gerekmiyor
5. Python ekosistemi: Celery (gorev kuyrugu), SQLAlchemy 2.0 (async ORM), asyncpg (PostgreSQL driver), Alembic (migration) gibi olgun kutuphaneler sorunsuz entegre olur
6. Dependency Injection: Depends() ile tenant izolasyonu, auth, DB session yonetimi temiz sekilde yapilir

Sonuclar

Olumlu

• Tek process'te HTTP + WebSocket + MQTT subscriber — operasyonel basitlik
• Otomatik OpenAPI sayesinde frontend-backend entegrasyonu hizlandi
• Pydantic ile runtime hatalari azaldi
• 25+ router modulu temiz bir sekilde organize edilebildi (features/ yaklasimi)
• Async DB sorgulari ile yuksek throughput

Olumsuz

• GIL (Global Interpreter Lock) CPU-bound islemlerde darbogazdir — Gunicorn multi-worker ile cozulmustur
• FastAPI surum guncellemelerinde Pydantic v1 → v2 gecisi onemli refactoring gerektirdi
• Async debugging, sync koda gore daha karmasiktir