Nedir Bu Mimari Karar Kaydı !
Kullandığımız her yazılımın arkasında o yazılımı geliştiren bilgisayar yazılımcıları vardır. Geliştirici (Developer) yazılımı oluştururken pek çok soruya cevap aranır.
Yazılımın ürün niteliği ile ilgili kararları ürün yöneticisi (Product Manager) ve ürün müdürü (Product Owner) verirken yazılımı oluştururken hangi mimarinin kullanılması gerektiği geliştiricilerle birlikte belirlenir.
Bir yazılım/sistem mimarisiyle ilgili kararların neden verildiğinin kayıt altına alındığı sürece ise Architecture Decision Record (ADR) denir.
ADR yaklaşımı, ilk olarak yazılım mimarı Michael Nygard tarafından 15 Kasım 2011’de yayımlanan “Documenting Architecture Decisions” adlı makaleyle ortaya kondu ve kavram bu yazıyla yaygınlaşmaya başladı.
ADR, kararın bağlamıyla (Contex), gerekçesiyle (Rationale) ve sonuçlarıyla (Consequences) birlikte kısa ve yapılandırılmış bir şekilde belgelenmesi demektir. Temel mantık “Bu kararı neden aldık” sorusunun cevabını bağlamla birlikte gelecekte erişilebilir hale getirmektir. Böylece gelecekte ekibe yeni katılacak geliştirici kararın neden veildiğini uzun toplantılar yapmak zorunda kalmadan öğrenebilir. ADR, geliştiricinin yeni uygulamada kullanacağı mimarinin eski yapı ile uyum içinde çalışması için seçeceği en makul kararı vermesi için yol göstericidir.
Standart bir ADR nin anatomisi şöyledir;
- Başlık (Title) : Kararın kısa özeti (ör. “ADR-014: Sipariş servisinde event-driven mimariye geçiş”)
- Durum ( Status) : Belgenin yaşam döngüsündeki yeri (Örn: Önerildi, Kabul Edildi, Reddedildi, Yürürlükten Kaldırıldı).
- Bağlam (Context): Kararı gerektiren durum, kısıtlar, alternatifler
- Karar (Decision): Net ifadeyle alınan karar
- Sonuçlar (Consequences): Kararın getirdiği faydalar, riskler, teknik borç, ileride dikkat edilmesi gerekenler
ADR şu sorulara yanıt arar;
- Hangi problem vardı ?
- Alternatifler nelerdir ?
- Neden bu aracı / uygulamayı / ürünü seçiyoruz ?
- Hangi kriter ve kısıtlara göre arar verdik ?
- Kararın avantaj ve dezavantajları nelerdir ?
- İleride hangi koşullar oluştuğunda bu karar tekrar değerlendirilmelidir ?
ADR’nin Tipik Yapısı
ADR ler uzun dokümanlar değildir. Önemli olan dokümanın uzun olması değil kararın izlenebilir olmasıdır.
ADR-001
Başlık:
Sipariş servisleri arasında Kafka kullanılması
Durum:
Accepted
Bağlam:
Sipariş oluşturma sonrasında birden fazla servisin
bilgilendirilmesi gerekiyor.
Değerlendirilen alternatifler:
- REST
- RabbitMQ
- Kafka
Karar:
Kafka kullanılmasına karar verilmiştir.
Kararın gerekçesi:
- Event-driven mimariye uygun olması
- Yüksek throughput
- Servislerin birbirinden bağımsız çalışabilmesi
Sonuçlar:
- Loose coupling
- Asenkron iletişim
- Kafka operasyonel maliyet getirir.
- Monitoring ihtiyacı oluşur.
Sonuç:
Sipariş eventleri Kafka üzerinden yayınlanacaktır.
ADR’nin Durumları (Status)
- Proposed (Önerildi): Önerildi ama henüz karar verilmedi, tartışma/değerlendirme aşamasında, resmi olarak onaylanmamış. Ekip veya mimari kurul (architecture board) incelemesi bekleniyor.
- Accepted (Kabul Edildi): Karar alındı , uygulanıyor. Sistem bu karara göre inşa edilmiş veya edilmekte. (Çoğu ADR’nin nihai/kalıcı statüsü budur.)
- Rejected (Reddedildi) : Öneri değerlendirildi ama reddedildi. Neden reddedildiği Context/Consequences bölümünde belgelenir — böylece aynı fikir tekrar gündeme geldiğinde “bunu zaten değerlendirmiştik, şu sebeple vazgeçmiştik” bilgisine hızlıca ulaşılır.
- Deprecated (Kullanımdan Kaldırıldı): Karar artık uygulanmıyor veya önerilmiyor — ancak yerine net bir “yeni karar” konulmamış olabilir (ör. teknoloji artık desteklenmiyor ama henüz alternatife geçilmedi).
- Superseded by ADR-XXX (Yerini Aldı) : Karar, daha sonra alınan başka bir ADR tarafından geçersiz kılınmış. Bu statü özellikle önemli çünkü karar tarihçesini zincirleme şekilde takip edilebilir kılıyor — “bu karar neden değişti, hangi yeni kararla değiştirildi” sorusuna doğrudan cevap verir.
ADR toplantısında hangi ekipler olmalı ?
ADR toplantısında bulunması gerekenler üç gruba ayırmak mümkündür
- Kararı Öneren ekip / mimar (Decision Owner) : ADR’yi yazan, kararın teknik gerekçesini savunan taraf Genelde ilgili domain’in mimarı veya senior developer’ı.
- Etkilenen sistem/servisin sahibi ekipler : Kararın doğrudan uygulanacağı veya entegre olacağı servisleri geliştiren ekipler. Onlar olmadan “context” eksik kalır.
- Etkilenmesi muhtemel ekipler : Karar uygulandığında operasyonel anlamda doğrudan ve dolaylı etkilenecek ekipler gerektiğinde katılmalıdır.
Örnek Temel Katılım Tablosu
| Rol / Ekip | ADR toplantısındaki rolü | Katılım |
|---|---|---|
| Software Architect / Solution Architect | Mimari kararın yönlendirilmesi ve değerlendirilmesi | Mutlaka |
| Development ekibi | Teknik uygulanabilirlik, geliştirme etkisi | Mutlaka |
| Ürün / Business temsilcisi | İş ihtiyacı ve business etkisi | Kararın iş etkisi varsa |
| DevOps / Platform | Infrastructure, deployment, CI/CD, cloud etkileri | Etkiliyorsa |
| Application Operations | Operasyon, monitoring, incident/problem, desteklenebilirlik | Operasyonel etkisi varsa |
| DBA / Data ekibi | Database, data model, performans, veri yönetimi | DB etkileniyorsa |
| Security | Güvenlik, authentication, authorization, compliance | Güvenlik etkisi varsa |
| Network | Network, firewall, connectivity, routing | Network etkisi varsa |
| SRE / Observability | Reliability, monitoring, alerting, SLO | Varsa ve etkileniyorsa |
ADR’lere Application Operations , Support Ekipleri Erişebilmeli mi?
Kesinlikle evet! Application Operatipns Support (AOS) ekipleri geliştirici ekip – iş birimi ve müşteri hizmetleri arasında köprü görevi görmektedir. Müşteriye temas eden bir sorun müşteri hizmetleri üzerinden ilk olarak support ekibine gelir ve AOS sorunu anlamaya, hızlı bir şekilde geçici çözüm üretmeye çalışır. Bunu yaparken yazılım mimarisini bilmek zorundadır. Application Operations’ın ADR’ye erişme amacı mimari kararları onaylamak değil, o kararların operasyonel sonuçlarını bilmek ve yönetebilmektir. Gerekçeler genel olarak şöyle sıralanabilir.
- Vaka çözümü (Incident) : Support ekipleri vaka çözümü sırasında “Order servisi neden doğrudan Product DB’ye bağlanmıyor?” , “Neden burada Kafka var?” , “Neden bu verinin cache’den okunması gerekiyor?” gibi sorulara ADR lere bakarak cevap bulabilmelidir.
- Vaka Çözümünde Yanlış Müdahale : Support ekipleri geçici çözüm uygularken sisteme zarar vermemek için mimariyi ADR’den teyit etmelidir. Aksi halde geri dönülmesi zor zararlar verebilir.
- İzleme ve Alarm : Support ekibi kararın sisteme getirdiği olumsuzlukları risk ve teknik borçları bilmelidir. Böylece hangi bileşenin daha zayıf veya kırılgan olduğunu, nerede darboğaz (bottleneck) yaşanabileceğini bilir. Hem yapacağı geçici çözümü bu kapsamda uygular hem de bu noktalar için gerekli izleme ve alarm mekanizmalarının kurulumunda rol oynar.
- Kapasite Planlama ve ölçeklendirme kısıtları : Support ekipleri DB seviyesinde yapacakları geçiçi çözüm aksiyonlarında sistemin ne kadar dayanabileceğini bilmelidir. Mesela “sistem maksimum saniyede 500 istek alacak şekilde tasarlandı” bilgisine erişildiğinde geçici çözüm bu kapsamda uygulanır.
- Destek ve Bakım Prosedürlerinin Korunması : Support ekibi destek süreçlerini Operasyonel Devir Dokümanı , Teknik Destek Dokümanı veya Run Bok gibi dokümanlarla bilgi bankasında tutar. Bir uygulamanın log stratejisi, hata yönetimi yaklaşımı yada dağıtım modeli değiştiğinde support ekibinin dokümantasyonu revize etmesi ve teknisyenlere değişimi indirmesi gerekir.
- Ortak Dil : Support ekibi yeni bir operasyonel süreç, durum veya otomasyon gereksinimini önerirken mevcut mimari kararlara referans vererek güçlü argümanlar üretebilmelidir. Aksi halde önerinin mimari yapıya uyumsuzluğu sebebiyle reddi söz konusu olabilir.
- Mimari Borç Tespiti : Support ekibi problem yönetim sürecinde bir sorunun kök sebebini ararken “Bu karar hangi trade-off lar ile alınmış, o zamanki kısıtlar hala geçerli mi” sorusuna cevap bulabilmelidir. Mesela ADR de “Database polling kullanılmasına karar verilmiştir” yazılmış ve aradan zaman geçmiş oluşan probleme istinaden yapılan incelemede “Polling mimarisinin değiştirilmesi gerekiyor” sonucuna varılabilir. Bu durum geçici fix ten kalıcı mimari iyileştirme önerisine doğru gidebilir.
- Postmortem – ADR geribildirim döngüsü : Support ekibi bir incident sonrası edindiği tecrübeyi “Bu karar production da şu şekilde sorun yarattı” iletebilmelidir. Böylece ADR ler zamanla teorik karar olmaktan çıkıp “gerçek dünya tecrübesiyle onaylanmış karar” haline gelmesini sağlar.
- Yeni Application Operations Üyelerinin Onboardingi : Değişim sadece geliştirici ekipte olmaz, support ekibinde yaşanan personel değişimlerinde ekibe yeni katılan personelin mimariyi anlayabilmesi için destek verdiği noktalara temas eden ADR lere erişmesi gerekir.
Kaynak : https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html
