ElementAPI

ElementAPI'yi açtığında karşına Türkçe bir kimya atlası çıkıyor; günlük maddelerin hangi elementlerden oluştuğunu kısa rotalarla anlatıyor. İçinde 118 element, 214 bileşik, altı öğrenme rotası, bir sözlük ve kişisel bir keşif koleksiyonu var. Kurcalamaya başlamak için hesap açman gerekmiyor, koleksiyonunu misafir olarak da tutabiliyorsun. Bence en eğlenceli yer /lab sayfası: elementleri sürükleyip bırakarak birleştiriyorsun, sonuç da hit, almost ya da impossible olarak dönüyor. "Formülü kur" ve "Dedektif" modları aynı fikri oyuna çeviriyor.

Atlasın arkasında ise .NET 10, Java 21 ve Node.js 22 ile yazdığım servislerden oluşan bir mikroservis platformu çalışıyor. Platformun ticaret tarafı sanal KREDI ile işleyen bir demo: mağazadan element alıyor, kasanda tutuyor, sonra masadan satabiliyorsun. Piyasa, stok, ödeme ve kargonun hepsi simülasyon; işin içinde gerçek para, borsa ya da fiziksel teslimat yok.

Verinin kaynağı ve açık v2 API'si

Elementlerin kütle, yoğunluk, sıcaklık, elektron dizilimi ve elektronegatiflik değerlerini PubChem, Royal Society of Chemistry ve NIST'ten (izotop bileşimleri) alıp sürümlenmiş bir dosyada tutuyorum. Her kayıt, provenance.sources[] altında kaynağın adresini ve retrieved_at tarihini taşıyor. Kaynakta bilinmeyen değerleri null bıraktım; atom numarası 119 gibi varsayımsal kayıtları da yayımlamıyorum. 214 bileşiğin hepsinde formül, molar kütle, PubChem CID ve 2D yapı görseli var. Bunların 51'i tam bir PubChem anlık görüntüsü; kalan 163'ü ise fiziksel ve GHS alanları boş, kısa eğitim kayıtları. Allotropları ve preparatları da saf bileşikmiş gibi sunmuyorum.

API çalışırken hiçbir dış kaynağa gitmiyor. Veriyi ayrı betiklerle ve ne zaman istersem o zaman yeniliyorum; Türkçe anlatım, görsel ve bağlantı katmanı da kendi betiğiyle yeniden uygulanıyor. Bilimsel kataloğun v2 sürümü herkese açık, yani sen de kullanabilirsin. GET /api/v2/elements/fe ya da GET /api/v2/compounds/h2o gibi çağrılarda alanları view, include ve fields ile seçiyorsun; yanıtlar ETag taşıyor, CORS da açık. Uygulamadaki /docs sayfası bu uçları canlı örneklerle gösteriyor.

Atlası tek başına da yayına alabiliyorum: science-service tek bir imaj olarak PostgreSQL, Redis ve RabbitMQ olmadan çalışıyor. Bu modda hesap ve ticaret kapalı, misafir koleksiyonu açık. Veri katmanını, v2 API'sini ve yayına alma kısmını atlas tarafını anlattığım yazıda koddan alıntılarla ayrıntılı yazdım.

.NET, Java ve Node arasında bir sipariş

Tam platformda bütün istekler YARP tabanlı bir gateway'den geçiyor. Gateway API anahtarını denetliyor, JWT'li istekleri yönlendiriyor ve hız sınırlarını uyguluyor. Arkasında identity, catalog ve compound (.NET 10), order (Node.js 22), wallet ve inventory (Java 21, Spring) servisleri çalışıyor; shipment ve notification servisleri ise saga'ya yalnızca RabbitMQ olaylarıyla katılıyor. Her servisin kendi veritabanı var; hepsi tek bir PostgreSQL instance'ının içinde duruyor.

Siparişi order-service yönetiyor, her adım bir olayla tetikleniyor:

POST /api/v1/orders      → OrderSubmittedEvent
  inventory  stok ayır   → StockReservedEvent
  order                  → PaymentRequestedEvent
  wallet     KREDI düş   → PaymentProcessedEvent / PaymentFailed
  order                  → ShipmentRequestedEvent
  shipment   kargo       → ShipmentDispatchedEvent
  order      Completed   → AssetsCreditedEvent, OrderCompletedEvent

Ayrı bir ödeme servisi yazmadım; ödemeyi wallet-service alıyor. Sipariş iptal edilirse ya da zaman aşımına uğrarsa telafi olayları yayımlanıyor: ayrılan stok serbest bırakılıyor, tahsil edilmiş KREDI de bir kez iade ediliyor. Sipariş tamamlanınca varlık kullanıcının kasasına işleniyor, stok kalıcı olarak düşüyor ve fiyata küçük bir dürtme uygulanıyor. notification-service de sipariş güncellemelerini SSRF korumalı bir order.updated webhook'u olarak iletiyor.

Aynı Idempotency-Key ile gelen bir sipariş yalnızca bir kez ücretlendiriliyor; aynı anahtarla farklı bir içerik gelirse 409 dönüyor. Miktar gram cinsinden ve en fazla dört ondalıkla gönderiliyor. Kasadaki her ürün symbol + compoundSlug ile ayrılıyor, yani NaCl'yi saf Na'ymış gibi satamıyorsun. Alış ve satış fiyatını sunucu hesaplıyor; bir siparişin tavanı 50.000 KREDI. İstek ve yanıtlardaki alan adları geriye dönük uyumluluk için eski *Elx biçiminde kaldı (balanceElx gibi); değerlerin KREDI olduğunu yanıttaki currency: "KREDI" söylüyor. Saga'nın servis servis nasıl işlediğini ilk yazıda anlattım.

Yayına alırken

Public overlay, Caddy'yi 80 ve 443'te açıyor ve TLS orada sonlanıyor; veritabanı ve servis portları dışarıya kapalı. Yerel compose'da da gateway ve web uygulaması dışındaki bütün portlar yalnızca 127.0.0.1'e bağlanıyor. Geliştirme sırları değiştirilmeden servisler Production modunda açılmıyor; sunucu modu yer tutucu sırları reddediyor.

Gateway kayıtta dakikada 5, auth POST'larında dakikada 15, genel trafikte de 10 saniyede 60 istek kabul ediyor. identity ise 5 hatalı şifre denemesinden sonra hesabı 15 dakika kilitliyor. Cüzdan ve sipariş yanıtları ortak yanıt önbelleğine girmiyor; iç servis çağrıları da ayrıca paylaşılan bir servis anahtarı istiyor. Derleme Jenkins Multibranch ile koşuyor.

Ön yüzü React, Vite, Tailwind CSS 4 ve Radix tabanlı bileşenlerle, "Mineral" adlı bir tasarım sistemi üzerine kurdum. Yalnızca koyu tema var ve tek vurgu rengi kuprit; başlıklarda Bricolage Grotesque, gövdede Geist, sembollerde, formüllerde ve kodda da Geist Mono kullanıyorum. Sistem kılavuzu docs/kilavuz/ altında, her servis için bir sayfa olarak duruyor. Aynı kılavuzu uygulamada /kilavuz adresinden okuyabilir, içinde arama yapabilirsin.

Açık kalan işler

Prometheus /metrics, HealthChecks UI ve ELK / Grafana yığınını bilerek kaldırdım; bu uçlar artık 404 dönüyor. Beta e-postasız çalışıyor, SMTP tanımlı değilse hesap kurtarma kapalı. JWT localStorage'da duruyor; httpOnly cookie ve refresh token iş listemde. 118 elementin 75'inin fotoğrafı var, uygun lisanslı görsel bulamadıklarımı boş bıraktım. Piyasa tek bir ev piyasa yapıcısından ibaret, emir defteri ve eşleştirme yok; kargo takibi de sahte. Bir de /kilavuz'daki altyapı sayfası compose'un yerel varsayılan sırlarını gösteriyor. Bunun herkese açık derlemede kalıp kalmayacağına henüz karar vermedim.

Kaynak kod: github.com/MihrimatriX/element-api.