Mimari Dokümantasyon, ADR ve Runbook'lar

Dokümantasyon, sistemin nasıl çalıştığını anlatmanın yanı sıra bir kararın neden alındığını ve arıza sırasında ilk hangi adımların uygulanacağını görünür kılar. Diyagram güncelliği, karar kaydı ve operasyon prosedürü aynı sahiplik modeline bağlanmalıdır.

Hızlı Karar

İhtiyaç	Belge	Dikkat
Sistem sınırlarını anlatma	Context/container/component diagram	Kaynak ve tarih bilgisi ekle
Request veya event akışını anlatma	Sequence/data-flow diagram	Sync/async sınırlarını göster
Mimari tercih kaydı	ADR	Karar, alternatif ve sonuç yaz
Tekrarlanabilir operasyon	Runbook	Preconditions, command ve rollback
Servis kataloğu	Service map	Owner, SLO, dependency ve data owner

Üretim Kontrol Listesi

• Problem: Belge hangi kararı veya operasyon adımını hızlandırıyor?
• Çözüm: Owner, audience, scope, last-reviewed tarihi ve source of truth belli mi?
• Trade-off: Ayrıntılı belge değerlidir; güncellenmiyorsa yanlış güven üretir.
• Hata durumu: Stale diagram, eksik rollback, yanlış alarm adımı ve gizli dependency ele alınmalı.
• Ölçüm: ADR review age, runbook success, incident MTTR ve broken-link sayısı izlenebilir.
• Güvenlik/maliyet: Secret, private endpoint ve müşteri verisi belgelere yazılmamalı.

Mimari Görünümler

En az şu görünümler gerektiğinde tutulur:

• Context: Kullanıcılar, dış sistemler ve sistem sınırı.
• Container/service: Servisler, queue, database, cache ve sahiplik.
• Component: Kritik servis içindeki modüller ve dependency yönü.
• Sequence: Başarılı istek, hata/retry, async completion ve failover akışı.
• Data flow: Verinin source of truth'tan projection, cache, backup veya analytics'e hareketi.

Her ok, protokol veya event adı, timeout/retry sınırı ve failure boundary ile anlamlı olmalıdır. Mermaid diyagramı kolay güncellenebilir tutulmalı; gerçek altyapı değiştiğinde diagrams-as-code veya source link ile drift azaltılmalıdır.

Service Map ve API Kataloğu

Service map her servis için owner/team, repository, runtime, region, SLO, data owner, inbound/outbound dependency, auth method, deploy yöntemi ve alert bağlantısını göstermelidir. API kataloğu endpoint/schema owner, lifecycle, version, rate limit, örnek ve deprecation tarihini ekler.

Bu bilgiler API Contract ve Tooling, observability ve incident süreçleriyle aynı service ID'yi kullanmalıdır.

ADR Formatı

Her ADR kısa ve değişmez bir karar kaydıdır:

# ADR-0042: Sipariş completion için queue kullanımı
Status: Accepted
Date: 2026-09-03
Context: İşlem request latency bütçesini aşıyor.
Decision: Queue + worker + job status kullanılacak.
Alternatives: Synchronous call, scheduled batch
Consequences: Eventual consistency, retry ve DLQ operasyonu

ADR, uygulama kodunun kopyası veya uzun tutorial değildir. Status proposed, accepted, deprecated, superseded olarak evrilebilir; yeni karar eskisini silmek yerine bağlantı kurmalıdır.

Runbook Tasarımı

Her runbook şu sırayı izlemelidir:

1. Impact: Hangi kullanıcı, SLO veya bölge etkileniyor?
2. Signal: Alert, dashboard, log ve trace nerede?
3. Safety: Yetki, blast radius, maintenance window ve durdurma koşulu.
4. Diagnosis: En düşük riskli kontroller.
5. Mitigation: Uygulanacak adımlar ve beklenen sinyal.
6. Recovery: Rollback, replay, failover veya traffic shift.
7. Verification: SLO, error rate, queue age ve kullanıcı akışı doğrulaması.
8. Follow-up: Incident kaydı, ADR veya kalıcı düzeltme.

Komutlar placeholder ve dry-run çıktısıyla verilmeli; password, token ve geniş kapsamlı destructive command eklenmemelidir. Runbook production erişimi olan kişi tarafından düzenli olarak tatbik edilmelidir.

Yaşam Döngüsü

Kod veya altyapı değişikliği, ilgili diagram/service map/ADR/runbook güncellemesini aynı review içinde taşımalıdır. Quarterly review, incident sonrası doğrulama ve broken-link kontrolü stale belgeyi azaltır. Bir belge artık karar veya operasyon değeri taşımıyorsa linkleri temizlenerek kaldırılmalıdır.