Mimari Diyagram Nasıl Çizilir? Yazılım Ekipleri İçin Adım Adım Rehber

İlk mimari diyagramınızı çizmeye oturduğunuzda zor olan kutuları çizmek değil, neyi dışarıda bırakacağınıza karar vermektir. Bu yazıda "mimari diyagram" derken bina mimarisini değil, yazılım ve sistem mimarisini kastediyoruz: servisler, veritabanları, kuyruklar, ağ bölgeleri ve bunların arasındaki bağlantılar. Aşağıdaki adımlar, ister ilk yazılım mimarisi diyagramınızı ister ekibinizin onuncu sistem mimarisi diyagramını çiziyor olun, okunabilir ve güncel kalan bir diyagram üretmeniz için yazıldı.

Önce okuyucuyu ve soruyu belirleyin

İyi bir diyagram tek bir soruya cevap verir. "Sistemimizdeki her şey" bir soru değildir; bu bir envanterdir ve envanteri diyagramda değil, tabloda tutmak daha iyidir.

Çizmeye başlamadan önce iki cümle yazın:

• Okuyucu kim? Ekibe yeni katılan bir geliştirici, nöbetçi SRE, güvenlik incelemesi yapan ekip, ürün yöneticisi ya da dış denetçi.
• Hangi soruyu cevaplıyor? "Bir sipariş isteği hangi servislerden geçiyor?", "Hangi bileşenler internete açık?", "Bir region çökerse trafik nereye gidiyor?"

Bu iki cümle diyagramın kapsamını belirler. Yeni gelen bir geliştiricinin ihtiyaç duyduğu ayrıntı ile ağ ekibinin ihtiyaç duyduğu ayrıntı aynı değildir. İkisini tek resme sığdırmaya çalışırsanız hiçbirine hizmet etmeyen bir diyagram elde edersiniz.

Doğru diyagram türünü seçin

Soru netleşince tür de büyük ölçüde kendiliğinden ortaya çıkar. C4 modeli iyi bir başlangıç noktasıdır: sistemi context, container, component ve code olmak üzere yakınlaştırma seviyelerine ayırır (ayrıntılar için c4model.com).

Emin değilseniz context diyagramıyla başlayın. Sistemin sınırını ve dış bağımlılıklarını netleştirir, sonraki diyagramlar için de bir çerçeve oluşturur.

Adım adım mimari diyagram çizimi

1. Kapsamı ve sınırı belirleyin

Diyagramın içinde ne olduğunu, dışında ne kaldığını yazın. Ekibinizin sahip olduğu bileşenler sınırın içinde durur; ödeme sağlayıcısı, kimlik sağlayıcısı ya da başka bir ekibin servisi gibi bağımlılıklar dışarıda kalır. Dış sistemleri tek bir kutu olarak gösterin, iç yapılarını çizmek size düşmez.

2. Bileşenleri listeleyin

Çizmeden önce bir liste çıkarın: servisler, veritabanları, kuyruklar, cache'ler, dış API'ler, kullanıcı tipleri. Her bileşene ekibin gerçekten kullandığı adı verin; repo ya da deployment adıyla birebir eşleşirse daha da iyi. Liste tek bakışta kavranamayacak kadar uzunsa büyük ihtimalle iki ayrı diyagramlık konunuz vardır.

3. İlişkileri etiketli, yönlü oklarla çizin

Etiketsiz bir çizgi okuyucuya yalnızca "bunlar bir şekilde ilişkili" der. Her oka bir yön ve en az iki bilgi verin: protokol ve amaç. Gerekiyorsa çağrının senkron mu asenkron mu olduğunu da ekleyin.

checkout-web  --[HTTPS/JSON · POST /orders · sync]-->  order-api
order-api     --[AMQP · order.created · async]------>  orders-queue
order-api     --[TCP 5432 · SQL · read/write]------->  orders-db

Ok, isteği başlatan taraftan alıcıya doğru gitsin. Cevaplar için ayrı ok çizmeyin; bu, çizgi sayısını gereksiz yere ikiye katlar. İstek ve cevabın sırası önemliyse sequence diyagramı tam da bunun için var.

4. Frame'lerle gruplayın

Gruplar diyagramın ikinci okuma katmanıdır. Bileşenleri anlamlı sınırların içine alın:

• Ağ bölgeleri: public subnet, private subnet, DMZ, şirket içi ağ
• Kubernetes namespace'leri: payments, platform, observability
• Region'lar ve hesaplar: eu-central-1, us-east-1, prod ve staging hesapları
• Güven sınırları: internetten gelen trafiğin nerede doğrulandığı

İç içe gruplar kullanabilirsiniz (region > VPC > subnet), ancak çok derine indikçe diyagram okunmaz hale gelir.

5. Lejant ekleyin

Renk, çizgi tipi ya da ikon bir anlam taşıyorsa lejantta yazmalıdır. Kesikli çizgi asenkron mesaj mı, kırmızı çerçeve PCI kapsamı mı? Çizen kişi için apaçık olan, altı ay sonra okuyan için açık değildir. Lejant küçük olabilir; önemli olan orada olmasıdır.

6. Başlık, tarih ve sahip ekleyin

Her diyagramın bir köşesinde üç bilgi bulunsun: neyi gösterdiğini söyleyen bir başlık ("Checkout — container görünümü, prod"), son güncelleme tarihi ve sahibi olan ekip. Tarihi olmayan bir diyagramın güncel olup olmadığını kimse bilemez; sahibi olmayan bir diyagramı da kimse güncellemez.

7. Çizmeyen biriyle gözden geçirin

Diyagramı, onu çizmemiş birine gösterin ve en başta yazdığınız soruyu sorun. Cevabı sizin açıklamanıza gerek kalmadan bulabiliyorsa diyagram işini yapıyor demektir. Sürekli "burada aslında şunu kastettim" diyorsanız, o açıklamayı diyagramın kendisine ekleyin.

Sık yapılan hatalar

• Her şeyi tek diyagrama koymak. Context, deployment ve ağ ayrıntısı aynı resimde olunca hiçbiri okunmaz.
• Etiketsiz ya da iki yönlü oklar. Kimin kimi çağırdığı belirsiz kalır; oysa bir incident sırasında en çok aranan bilgi tam olarak budur.
• Tutarsız soyutlama seviyesi. Bir kutu "Ödeme Sistemi", yanındaki kutu "Redis pod'u" ise okuyucu ölçeği kaybeder.
• Anlamı açıklanmayan renkler. Lejantta karşılığı olmayan renkler ya süstür ya da yanlış yorumlanır.
• Sahipsiz ve tarihsiz diyagramlar. Wiki'de duran, kimin çizdiği belli olmayan bir diyagram zamanla yanlış bilginin kaynağına dönüşür.

Diyagramı güncel tutmak

Bir diyagram ancak ona güvenildiği sürece işe yarar. Birkaç alışkanlık bunu kolaylaştırır:

• Diyagramı anlattığı sistemin dokümantasyonuna yakın tutun; README'den ya da runbook'tan link verin.
• Mimariyi değiştiren pull request'lerin kontrol listesine "diyagram güncellendi mi?" maddesini ekleyin.
• Büyük değişikliklerden önce bir revizyon saklayın; "geçen çeyrek nasıldı?" sorusunun bir cevabı olsun.
• Sahip ekibin diyagramı düzenli aralıklarla, örneğin her çeyrek, gözden geçirmesini takvime koyun.

Archboard'da yazılım mimarisi diyagramı çizmek

Archboard, platform ve ürün ekipleri için bulutta çalışan bir mimari çalışma alanıdır. Yukarıdaki adımlar her araçla uygulanabilir; Archboard'da şöyle görünür:

1. Giriş yapın. Giriş sayfasından Google ya da GitHub hesabınızla girin. İlk girişte hesabınız ve organizasyonunuz oluşturulur, kredi kartı istenmez.
2. Paketleri seçin. Archboard'da 27 yerleşik paket ve 223 node tipi var. İlk diyagram için çoğu zaman şunlar yeter:
   • C4 Model: Person, Software System, Container, Component, Database ve boundary'ler; context ve container diyagramları için.
   • Kubernetes: Namespace (frame olarak çizilir), Deployment, Pod, Service, Ingress, ConfigMap, Secret, PVC, HPA, NetworkPolicy ve diğerleri.
   • Cloud: bulut altyapısı için; çok hesaplı haritalarda kullanılan k8s-cluster node'u da bu pakette.
   • Network: ağ bölgeleri ve bağlantılar için.
3. Port'ları bağlayın. Node'lar sıradan şekiller değil, port'ları olan birinci sınıf node'lardır. Bağlantıyı port'tan port'a çekin ve oka protokolü ve amacı yazın.
4. Frame'lerle gruplayın. Core paketindeki Frame ile ağ bölgelerini ve region'ları, Kubernetes Namespace ile namespace'leri, C4 boundary'leri ile sistem sınırını çizin.
5. Başlık ve lejant ekleyin. Canvas'a bir Markdown bloğu ya da Table koyun; başlık, tarih, sahip ve lejant tek yerde dursun.
6. Paylaşın. Public paylaşım linkini gözden geçirecek kişiye gönderin (Free planda link Archboard markalıdır). Pro ve Enterprise'da diyagramı iframe ile dokümantasyon sitenize gömebilirsiniz.
7. Dışa aktarın. SVG ya da PNG alın (Free'de filigranlı); Pro'da JPEG, PDF ve animasyonlu GIF / WebM de gelir, hepsi filigransız. Diyagram dokümanını yapılandırılmış JSON olarak da dışa aktarabilirsiniz.

Değişiklikler otomatik kaydedilir ve her diyagram revizyon tutar: Free'de son 5 revizyon, Pro'da bir yıllık, Enterprise'da ise süre sınırı olmayan geçmiş. Free tüm yerleşik paketleri, 3 diyagramı ve diyagram başına 15 diyagram node'u + 150 not, metin, çıkartma ve zihin haritası konusunu içerir; ilk context diyagramı için fazlasıyla yeterli. Tam deployment haritaları için Pro sınırsız diyagram ve node sunar. Ayrıntılar için fiyatlandırma sayfasına bakın.

Başlamadan önce örnek galerisine göz atın: Herkese açık bir örneği açın ve Bu örneği kullan ile çalışma alanınıza kopyalayın (diyagram kotanıza sayılır). C4 ve Kubernetes ayrıntıları için C4 kullanım senaryosu ve Kubernetes kullanım senaryosu sayfalarına bakın. İlk fikirler de aynı canvas'ta başlayabilir: Archboard'da mimari paketlerin yanında sticky note'lar ve mind map'ler de var.

Kontrol listesi ve sık sorulan sorular

Yayınlamadan önce:

• Okuyucu ve soru yazılı
• Sınır net, dış sistemler tek kutu
• Her ok yönlü ve protokol + amaç etiketli
• Gruplar ağ bölgesi, namespace ya da region gibi gerçek sınırları gösteriyor
• Lejant, başlık, tarih ve sahip var
• Diyagramı çizmeyen biri soruyu cevaplayabildi

Mimari diyagram ile akış şeması arasındaki fark nedir? Mimari diyagram yapıyı gösterir: hangi bileşenler var ve nasıl bağlılar. Akış şeması (flowchart) bir sürecin adımlarını ve karar noktalarını gösterir. Bir isteğin zaman içindeki sırası önemliyse sequence diyagramı daha uygundur.

Kaç diyagram çizmeliyim? Okuyucu ve soru çifti kadar. Çoğu sistem için bir context, bir container ve bir deployment diyagramı iyi bir başlangıçtır.

Hangi aracı kullanmalıyım? Çizdiğiniz kavramları tanıyan bir araç. Archboard; Kubernetes, C4 ve bulut kavramlarını portlu, hazır node'lar olarak sunar; böylece diyagramınız okunabilir kalır ve güncel tutmak kolaylaşır. Hangi aracı seçerseniz seçin, asıl test diyagramın sorunuzu cevaplayıp cevaplamadığıdır.

Ücretsiz başlayın — tek kullanıcı, kredi kartı gerekmez.