İkas’ta Tema Scripti mi, Özel Uygulama mı? Doğru Entegrasyon Mimarisi Nasıl Seçilir?

İkas mağazasında özel bir geliştirme yapılacağı zaman ilk çözüm çoğu zaman “Tema içine JavaScript ekleyelim” olur.

Bu bazı problemler için doğrudur. Ancak feature büyüdükçe tema script'i API çağırmaya, müşteri ayarı tutmaya, sipariş işlemeye, webhook dinlemeye ve farklı mağazalarda çalışmaya başlıyorsa artık yanlış abstraction'da olabilir.

Temel soru “Bunu yapabilir miyiz?” değil, “bu logic nerede yaşamalı?” olmalıdır.

Dört temel entegrasyon katmanı

1. Tema / Studio logic

UI ve storefront behavior.

2. Storefront Events script

Kullanıcı ve commerce event'lerini client-side yakalama.

3. Backend webhook listener

Sipariş/stok/iade gibi server-side olaylara tepki verme.

4. Admin/Custom App

Kalıcı ayar, API erişimi, merchant UI ve geniş business logic.

Tema logic ne zaman doğru?

• cart drawer,
• mobile menu,
• variant selector,
• UI animation,
• quick-add,
• component-level interaction.

Tema içine ne koymamalıyız?

“Sipariş gelince ERP'ye gönder” browser interaction değildir. Kullanıcının sayfayı açık tutmasına bağımlı olmamalıdır. Backend event'tir.

Storefront Events ne zaman kullanılmalı?

• analytics,
• marketing integrations,
• behavior tracking,
• client-side third-party integrations.

Analytics için DOM dinlemek neden kötü?

document.querySelector(".add-to-cart") gibi DOM hack'leri tema değişince bozulabilir. Daha doğru çözüm commerce event → subscriber mimarisidir.

Storefront script nasıl deploy edilmeli?

Harici JavaScript'i ayrı deployment ortamında host etmek integration kodunu theme bundle'dan ayırabilir ve versioning/deployment süreçlerini temizler.

Ne zaman backend webhook gerekir?

Sipariş oluştuğunda ERP'ye gönderme gibi işlemler için doğru model:

Order Created → Webhook → Backend → Queue → ERP

Webhook'ta doğrudan ERP çağırmak doğru mu?

Küçük projede çalışabilir. Scalable architecture için Webhook → Validate → Persist / Queue → Worker → ERP daha güvenlidir.

Idempotency kritik

Aynı order_id + event_type birden fazla kez gelirse ERP'de duplicate işlem oluşmamalıdır.

Ne zaman özel uygulama geliştirmeliyiz?

• merchant ayar ekranı,
• OAuth/API erişimi,
• kalıcı configuration,
• birden fazla mağazada kullanım,
• background processing,
• webhook subscription,
• ürün/sipariş/müşteri verisiyle aktif çalışma.

Basit karar tablosu

Custom app mi public app mi?

Feature yalnız tek marka için geliştiriliyorsa public marketplace ürünü yapmak gereksiz olabilir. Çok sayıda mağazada kullanılacaksa configuration, versioning ve tenant isolation düşünülmelidir.

Multi-tenant app architecture

Tenant → Store / Credentials / Settings / Webhooks / Integration State

Merchant-specific logic kod içinde if store === X olarak büyümemelidir; configuration-driven olmalıdır.

API erişimi hangi katmanda olmalı?

Admin API token'ı browser'a koymak yanlış olur. Admin API interaction backend üzerinden yapılmalıdır.

Entegrasyon architecture checklist

• Feature UI mı backend işi mi?
• Browser açık değilken çalışması gerekiyor mu?
• Merchant ayarı var mı?
• API credential gerekiyor mu?
• Secret browser'a sızıyor mu?
• Webhook gerekiyor mu?
• Retry ve idempotency var mı?
• Birden fazla mağazada çalışacak mı?
• Tenant isolation var mı?
• DOM hack var mı?
• Logging ve queue gerekiyor mu?
• Rate limit yönetiliyor mu?

En sık yapılan hata

Her özelliği theme customization olarak başlatmak. Sonra theme.js API, analytics, CRM, ERP, campaign, cart ve customer logic yapmaya başlar. Bu noktada theme frontend olmaktan çıkıp kontrolsüz application layer haline gelir.

Doğru separation

Theme → Presentation + Interaction
Storefront Events → Client-side commerce signals
Backend → Business logic + integrations
App → Configuration + API + merchant experience
Webhooks → Asynchronous commerce events

Entegrasyon seçimi için üç soru

1. İşlem browser kapanınca da devam etmeli mi?
2. Gizli credential gerekiyor mu?
3. Retry/idempotency gerekiyor mu?

Üçünden biri evetse yalnız tema script'i büyük ihtimalle yanlış katmandır.

Tema script'ine uygun işler

• UI enhancement,
• basit analytics event,
• görsel widget,
• kullanıcı etkileşimi.

Backend/app gerektiren işler

• ERP sync,
• webhook,
• secret API,
• order mutation,
• async job,
• bulk operation.

Event-driven entegrasyon

Order Created
→ webhook receiver
→ verify signature
→ persist event
→ queue
→ ERP adapter
→ retry/dead-letter

Webhook request içinde ERP'ye senkron çağrı yapmak sistemi kırılgan yapar.

Idempotency

Unique key:

provider_event_id

veya resource/version kombinasyonu duplicate processing'i engelleyebilir.

Multi-tenant özel uygulama

• merchant_id,
• encrypted credentials,
• per-tenant rate limits,
• scoped logs

gerektirir.

Theme → app communication

theme/browser
→ public/BFF endpoint
→ app backend
→ third-party

Secret browser'a taşınmamalıdır.

Failure mode

ERP down olduğunda storefront çalışmaya devam etmelidir. Critical commerce path ile async integration path ayrılmalıdır.

Observability

Her job merchant, event, attempt, latency, result ve error ile loglanmalıdır.

Karar tablosu

Teknik borç sinyalleri

Tema script'inin özel app'e taşınma zamanının geldiğini gösteren işaretler:

• localStorage üzerinden kritik state,
• gizli API key'i browser'a koyma ihtiyacı,
• üçten fazla retry hack'i,
• aynı scriptin merchant bazlı branch'lerle büyümesi,
• support için log bulunmaması.

Bu sinyaller görüldüğünde sorun script kalitesi değil, katman seçimidir.

Sonuç

İkas üzerinde özel geliştirme yaparken en kritik karar kullanılan framework değil, sorumluluğun hangi katmana ait olduğudur.

Reliefers olarak İkas projelerinde tema koduna feature eklemekten önce feature'ın yaşam döngüsünü değerlendiriyoruz. Özellikle ERP, CRM, analytics ve operasyon entegrasyonlarında doğru separation hem performansı hem bakım maliyetini hem de ölçeklenebilirliği belirliyor.