Backend Genel Bakış

Zeus 2.0 backend'i FastAPI 0.115 üzerine kurulu, tamamen async/await pattern kullanan bir Python 3.11 uygulamasıdır.

Temel Yapı

• 29 router — Feature-based modüler API
• 4 middleware — CORS, RequestLogging (structlog), TenantContext, GZip (>500 bytes)
• 65+ SQLAlchemy model — UUID PK, timestamp mixin (core/database/models.py + features/zigbee/models.py)
• 7 Celery task modülü — 11 periyodik görev

Uygulama Yaşam Döngüsü

Startup

1. Template'leri memory cache'e yükle
2. Device template DB senkronizasyonu
3. RBAC permission doğrulama (dev mode)
4. MQTT client başlat (tüm worker'lar)
5. MQTT subscriber başlat (sadece leader worker)
6. Zombie batch OTA job'larını temizle
7. OTA ve Zigbee MQTT handler'larını kur
8. Zigbee measurement batch service başlat
9. Redis cache başlat
10. Rawconfig push (5s delay sonrası tüm gateway'lere)
11. Periyodik stale cleanup başlat (30dk interval)

Shutdown

1. Startup rawconfig push task iptal
2. Periyodik stale cleanup task durdur
3. Zigbee measurement batch service durdur
4. MQTT subscriber durdur + leadership release
5. MQTT client kapat
6. Redis bağlantı kapat

Multi-Worker MQTT Stratejisi

Gunicorn ile 2 worker çalıştırılır. MQTT mesaj kaybını önlemek için:

• MQTT Client: Tüm worker'lar bağlanır (publish yapabilmek için)
• MQTT Subscriber: Sadece leader worker subscribe olur
• Leadership: /tmp/zeus_mqtt_leader.lock dosya kilidi ile belirlenir
• Failover: Worker çökerse kilit serbest kalır, diğer worker lider olur

# gunicorn.conf.py
workers = 2
worker_class = "uvicorn.workers.UvicornWorker"
max_requests = 1000        # Memory leak önleme
max_requests_jitter = 50   # Kademeli restart
timeout = 90

Feature Modül Yapısı

Feature modülleri genellikle şu yapıdadır (ancak her modül tüm dosyaları içermeyebilir):

features/devices/
├── router.py      # FastAPI endpoint tanımları
├── schemas.py     # Pydantic request/response şemaları
├── models.py      # SQLAlchemy modelleri (veya core/database/models.py'den import)
└── service.py     # İş mantığı

not

Bazı modüller bu yapıya tam uymaz. Örneğin gateway_config sadece service.py içerir; telemetry modülünde schemas.py ve models.py yoktur; firmware modülünde service.py ve models.py yoktur; attached_devices ve memberships modüllerinde service.py ve models.py yoktur (sadece router.py + schemas.py). Modellerin büyük çoğunluğu core/database/models.py'de merkezi olarak tanımlıdır.

Exception Handling

Global exception handler'lar main.py'de tanımlıdır:

• ValueError → HTTP 400 Bad Request
• Genel Exception → HTTP 500 Internal Server Error (production'da detay gizlenir)

Health Check Endpoint'leri

Endpoint	Amaç	Kullanım
GET /health	MQTT durumu ile ok/degraded	Docker health check
GET /readiness	DB bağlantı kontrolü	Kubernetes readiness probe
GET /api/config/public	Frontend runtime config	Google Maps API key
GET /metrics	Prometheus metrikleri (ASGI mount)	Monitoring & alerting