ADR (architecture decision records)

Mimari kararlar genellikle toplantı notlarında, kaybolan Slack mesajlarında veya kimsenin hatırlamadığı varsayımlarda yaşar. Altı ay sonra neden PostgreSQL sectik? sorusu cevapsiz kalir. Architecture Decision Record (ADR), tek bir mimari karari yapisal olarak belgeleyen hafif bir formattir. Michael Nygard tarafindan populerlestirilen ADR, kod kadar karar gecmisini de versiyonlamayi mümkün kilar.

ADR nedir

ADR, belirli bir mimari kararin baglamini, secilen çözümü, alternatifleri ve sonuclarini kaydeden kisa bir markdown belgesidir. Her ADR bir karar; depo icerisinde kronolojik numaralandirilir: 0001-use-postgresql.md, 0002-event-bus-rabbitmq.md.

Amac uzun mimari doküman üretmek degil; gelecekteki okuyucuya (genellikle gelecekteki siz) karar mantigini aktarmaktir.

Temel şablon

# ADR-0003: Mediator pattern for application layer

## Status
Accepted

## Context
Controllerlar sisiyor; cross-cutting validation daginik.

## Decision
MediatR ile CQRS handler pipeline kullanilacak.

## Consequences
+ Ince controller, test edilebilir handler
- Yeni gelistiriciler icin ogrenme egrisi
- Handler discovery icin assembly taramasi gerekir

Şablon esnek tutulur; ekip ihtiyacina gore alan eklenir.

Durum yaşam dongusu

ADR durumlari net olmalidir:

• Proposed: Tartisma devam ediyor.
• Accepted: Uygulaniyor.
• Deprecated: Artik geçerli degil ama tarihsel referans.
• Superseded by ADR-00XX: Yeni karar ile degistirildi.

Eski ADR silinmez; uzerine cizilmez. Superseded link ile zincir korunur.

Ne icin ADR yazilir

Her karar ADR gerektirmez. ADR yazmaya deger durumlar:

1. Geri donusu zor veya pahali kararlar.
2. Alternatifler arasinda tartisma olan konular.
3. Güvenlik, veri veya uyumluluk etkisi yüksek seçimler.
4. Ekipler arasi anlasma gerektiren sınır kararlari.

int x = 1 gibi triyal kararlar ADR olmamali; doküman gurultusu yaratir.

ADR vs RFC vs design doc

RFC genellikle onay oncesi geniş tasarım tartismasi icindir. Design doc uygulama detayini tasir. ADR kapanmis kararin ozetidir. Büyük degisiklikte once RFC, implementasyon sonrasi veya paralel ADR mantiklidir.

Depolama ve kesif

ADRler repo icinde docs/adr/ klasorunde tutulur; kod ile ayni PRda review edilir. README veya index dosyasi tüm ADRleri listeler. IDE ve arama araclari ile kesfedilebilir olmalidir.

Arsiv yönetimi

Yillar icinde ADR sayisi artar. Index dosyasi kategori etiketleri tasiyabilir: database, messaging, security. Arsiv degerlidir; silmeyin.

Review süreci

ADR PR olarak acilir. En az bir senior muhendis ve etkilenen ekip temsilcisi onaylar. Tartisma PR yorumunda yapilir; karar Accepted oldugunda merge edilir. Bu süreç karar sahipligini netlestirir.

Örnek karar alanlari

• Monolit mi mikroservis mi
• Sync REST mi async messaging mi
• Multi-tenant veri izolasyon stratejisi
• Observability stack seçimi
• Authentication modeli

Her alan icin Context bolumu is kisitlarini açık yazar: ölçek, butce, ekip yetkinligi, mevzuat.

Consequences bolumu

En cok atlanan bölüm Consequencesdir. Olumlu ve olumsuz etkiler açık yazilmali. Örneğin event-driven seçimi operasyonel karmasiklik getirir; bu gizlenmemeli. Gelecekteki okuyucu trade-offu anlar.

ADR ve teknik borc

Bilincli teknik borc ADR ile kayıt altina alinabilir: Decision hızlı çözüm, Consequences faiz aciklamasi. Borc geri odendiginde yeni ADR oncekini supersede eder.

Ölçek ve ekip kulturu

Küçük ekipte ADR hafif tutulur; büyük organizasyonda ADR template zorunlu olabilir. Önemli olan ritimdir: karar kapatildiginda ADR yazmak aliskanlik haline gelmelidir.

Anti-patternler

1. Implementasyondan sonra ADR yazip mantigi uydurmak.
2. Status guncellememek; Accepted ama uygulanmiyor.
3. Cok uzun ADR; okunmaz hale gelir.
4. ADRyi hic referans etmemek; olumlu dokunulmaz kil yapmak.

Araclar

adr-tools CLI yeni ADR iskeleti oluşturur. Log4brains gibi portal ADRleri webde sunar. Ancak arac zorunlu degil; markdown dosyasi yeterlidir.

Özet

ADR mimari hafizadir. Context, Decision, Consequences ile gelecekteki tartismalar veriye dayanir. Repo icinde versiyonlanan ADRler onboarding hizlandirir ve gereksiz yeniden tartismayi onler. Karari belgeleyin; varsayimi degil.

Ilk bes ADR onerisi

Yeni proje baslarken su kararlar erken yazilir:

1. Veritabanı ve persistence stratejisi
2. API stili ve surumleme
3. Authentication ve authorization modeli
4. Logging ve observability
5. Deployment ve ortam yapisi

Erken ADRler sonradan catisma azaltir.

Multiteam senaryo

Platform ADRleri tüm ekiplere baglayici olabilir. Domain ADRleri bounded context icinde kalir. Catisma durumunda architecture guild karar verir ve ADR güncellenir.

ADR ve compliance

Denetim gerektiren sektorlerde ADR karar izi sağlar. Veri saklama bolgesi, sifreleme standardi ve erişim modeli ADR ile arsivlenir. Denetci neden belirli bir kontrol secildigini ADR zincirinden okur.

Localization

Global ekiplerde ADR ana dil Ingilizce tutulabilir; özet cevirisi opsiyoneldir. Karar terimleri tutarlı sozlukte tanimlanir.

Metrikler

Accepted ADR sayisi, superseded orani ve ortalama karar suresi mimari olgunluk gostergesi olabilir. Amac ceza degil seffafliktir.