Archify Nedir? Kodunu Anlaşılır Diyagramlara Dönüştür

Neden böyle bir araca ihtiyaç var?

Herkes şu anı yaşamıştır: Yapay zekaya “projemin mimarisini çizer misin?” dersin, ortaya süslü ama hatalı bir şema çıkar. Bir ok yanlış kutuya gider, bir servis aslında yokken varmış gibi çizilir, yazılar üst üste biner ve kimse fark etmez. Mermaid gibi araçlarda da aynı sorun var: yapay zeka serbestçe metin yazar, hata sessizce resme dönüşür.

Basitçe: Diyagram, binanın elektrik planı gibidir — prizin nereye bağlı olduğunu tek bakışta gösterir. Yapay zeka plansız çizerse kablo şeması yanlış olur ve kimse hatayı fark etmez. Archify, önce liste (JSON — kurallı bir madde listesi) yazar ve o listeyi tek tek kontrol eder; resim en son gelir.

Örnek: Mutfakta tarif defterine "3 yumurta" yazmadan doğrudan omlet yapmaya benzer — ölçü yoksa sonuç şans işi olur.

Archify bunu tam tersine çeviriyor. Yapay zekaya “çiz” demiyor, “önce neyin neye bağlı olduğunu kurallı bir liste olarak yaz” diyor. Bu liste çizilmeden önce 9 ayrı kontrolden geçiyor. Yazılar üst üste mi bindi? Ok bir kutunun içinden mi geçiyor? Kurallara uymayan bir şey var mı? Varsa resim hiç oluşmuyor; sistem “şurada hata var, şunu düzelt” diye geri bildirim veriyor. Yani modelin hayal gücü ile son resim arasında bir güvenlik kapısı var.

Kurulum — tek satır, 30 saniye

Archify tek başına bir uygulama değil. Zaten kullandığın yapay zeka aracının (Claude Code, Cursor, Codex, OpenCode) içine eklenen bir yetenek. Bilgisayarında Node 18 veya üzeri olması yeterli; güçlü bir ekran kartı, özel bir kurulum gerekmiyor.

Ne demek Node 18? Bilgisayarınızda JavaScript çalıştırmaya yarayan programın sürümü. Sürüm 18, son 2–3 yılda çıkmış her bilgisayarda zaten vardır; ekran kartı gerekmez. npx skills add tt-a1i/archify -g demek, "bu yeteneği benim yapay zeka aracıma ekle, her projede kullanabileyim" demektir (-g = global, her yerde).

Takılırsa: Yapay zekanıza şunu söyleyin: "GitHub'daki tt-a1i/archify reposundan yeteneği yükle" — bu cümle Cursor'da neredeyse her zaman çalışır.

npx skills add tt-a1i/archify -g

Cursor kullanıyorsan sitesindeki yönlendirici sana tam komutu veriyor (global mi proje içi mi). Kurduktan sonra iki kısa kontrol yap:

node bin/archify.mjs doctor
# → “hazır” ve Node sürümünü söyler

node bin/archify.mjs guide "Show an API request with a Redis cache miss" --json
# → hangi diyagram tipinin uygun olduğunu önerir, resim oluşturmaz — sadece yol gösterir

Not: Bazı araçlarda global eklenen yetenekler hemen görünmeyebiliyor. Böyle olursa GitHub linkini doğrudan yapay zekana ver: “Bu repodan yeteneği yükle ve kullan” demek genelde yetiyor. Cursor’da genelde sorunsuz çalışıyor.

Büyüt

5 diyagram tipi — hangisi ne işe yarar?

Önce “neyi anlatmak istiyorum?” diye sor. Archify’da her anlatım için ayrı bir şablon var. Hepsi aynı güvenlikten geçiyor ama farklı sorulara cevap veriyor:

Hangi soruya hangisi? "Neler var?" diyorsan harita (architecture), "Sıra ne?" diyorsan adım adım akış (sequence), "Kim onaylıyor?" diyorsan iş akışı, "Veri nereye gidiyor?" diyorsan veri yolculuğu, "Durum nasıl değişiyor?" diyorsan durum (state). Yanlış tipi seçmek, yanlış harita kullanmak gibidir — yol tarifini bina planından okumaya çalışmak.

Kısa kural: “Neler var?” → harita, “Sırayla ne oluyor?” → sıralı adımlar, “Kim onaylıyor?” → iş akışı, “Veri nereye akıyor?” → veri yolculuğu, “Durum nasıl değişiyor?” → durum. Emin değilsen guide komutunu sor — sana en uygununu önerir.

Büyüt

Arka planda ne oluyor? (basitçe)

Hiç kod bilmeden şöyle düşün: Yapay zekaya “çiz” demek yerine “maddeler halinde listele” diyorsun. Örneğin: “Tarayıcı API’ye istek atar, API Redis’e bakar, bulamazsa veritabanına gider…” Bu liste, herkesin uyduğu bir forma yazılıyor (teknik adı JSON). Formda yazım hatası veya boş alan varsa sistem direkt reddediyor — “bilinmeyen alanı kabul etmem” diyor.

Ilkokul örneği: Öğretmene "resim çiz" demek yerine "önce 4 cümleyle anlat, sonra o cümlelere göre çiz" demek. Öğretmen cümlende yazım hatası varsa kâğıdı geri verir. Archify'da da program, yapay zekanın yazdığı listeyi aynı titizlikle geri çevirir; yerleşimi (kutuların yeri) program hesaplar, bu yüzden yazılar kaymaz.

Sonra bu liste 4 aşamadan geçiyor: (1) yapay zeka listeyi yazar, (2) program listeyi kontrol eder, (3) doğruysa resmi çizer, (4) tek bir HTML dosyası olarak paketler. Her adımda kapı var; hatalıysa bir sonraki adıma geçmiyor ve “şunu düzelt” diye geri dönüyor. Yerleşimi (kutular nereye gelecek) yapay zeka değil, program karar veriyor — o yüzden yazılar kaymıyor, oklar kutuların içinden geçmiyor.

Büyüt

Renk ve tema ayarları (classic, signal-flow, blueprint, editorial) sadece görünümü değiştirir; kutuların yeri ve bağlantılar aynı kalır. Hareketli izler (trace) isteğe bağlı — normalde resim duruyor ki dikkat dağılmasın.

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Cache-miss yolu", "visual_preset": "signal-flow" },
  "components": [ ],
  "boundaries": [ ],
  "connections": [ ]
}

İlk diyagram: “cache miss” örneği

Videolarda en çok gösterilen örnek bu: Tarayıcı → API → Redis (hızlı bellek) → Postgres (ana veritabanı). Soru net: “Cache’de yoksa ne oluyor?” Eğer “bütün projeyi çiz” dersen sonuç çorba olur. Archify’ın altın kuralı: bir diyagram = bir soru, en fazla 8–12 kutu, tek bir ana yol.

Gündelik benzetme: Büfe — müşteri sorar (tarayıcı), tezgahtar önce hızlı çekmeceye (Redis — hızlı bellek) bakar, orada yoksa depoya (Postgres — ana veritabanı) gider, alınca çekmeceye bir kopya koyar, müşteriye verir. Ertesi sefer aynı soru gelirse çekmeceden anında verir. Archify'a "cache miss ne oluyor?" diye sorduğunda tam bu 4 adımı tek resimde gösterir.

Altın kural: Bir resim = bir soru, en fazla 8–12 kutu, tek ana yol. "Her şeyi çiz" dersen mutfak, depo ve kasayı aynı kâğıda sıkıştırmaya benzer — okunmaz.

Benim kullandığım hazır kalıp:

Use Archify architecture diagram, 8 to 12 nodes max.
What happens on a cache miss in the service?
Only include boxes that exist in this repo.
If you can't prove a component, omit it.
Deliver a self-contained HTML.

Bu 4 cümle şunu söylüyor: “Kısa tut, sadece gerçekten var olanı çiz, kanıtlayamıyorsan ekleme, sonunda tek dosya ver.” 7 videonun 4’ünde neredeyse aynı cümle var — tesadüf değil, işe yaradığı için tekrarlanıyor.

Büyüt

Bu örnek iyi bir alıştırma çünkü sırayı bozarsan hemen belli oluyor. Videolardan birinde ilk denemede yazılar üst üste binmiş, bir etiket kutuya sığmamış. Sistem “92 piksele 102 piksellik yazı sığmıyor” demiş, yapay zeka da kutuyu 132 piksele genişleterek çözmüş — yazıyı değiştirmeden.

Gerçek kodu haritalamak: React Native örneği

İkinci videoda çok basit bir cümleyle başlanıyor: “React Native nasıl çalışıyor, basitçe anlat.” Archify buna rağmen Hermes, Turbo Modules, Device APIs, Shadow Tree gibi parçaları ayırıp aralarındaki bağı bir haritaya döküyor. Sunum modunda bu haritayı adım adım oynatabiliyorsun, bir kutuya tıklayıp “bu parça kime bağlı?” diye izole edebiliyorsun, açık/koyu temayı değiştirebiliyorsun.

React Native nedir, kısaca? Telefon uygulaması yazma yöntemi: tek kod, hem iPhone hem Android. Archify, "React Native nasıl çalışıyor?" sorusuna Hermes (hızlı JavaScript motoru), Turbo Modules (hazır parçalar), Shadow Tree (ekrandaki ağaç) gibi 9 parçayı ayırıp "kim kime bağlı?" haritasını çıkarır. Sunum modunda bu haritayı slayt gibi adım adım oynatabilir, "sadece bu kutuyu göster" diyebilirsin.

SRC rozeti ne? Kutunun köşesinde küçük "SRC" yazıyorsa, o parça gerçekten kodda bulunmuş ve satır numarasıyla kanıtlanmıştır. Rozet yoksa fikir doğrudur ama kanıtı yoktur — ikisini karıştırmamak gerekir. Gerçek projede "sadece kanıtlı olanı çiz" komutu bu yüzden verilir.

Gerçek projende fark şurada: Yapay zeka kodu tarar ama “gördüm” demesi yetmez. Archify’da bir kutunun yanında küçük SRC rozeti varsa, o parça gerçekten kodda var ve commit + satır numarasıyla kanıtlanmış demektir. Rozet yoksa, o kutu ne kadar mantıklı görünse de kanıtı yok demektir. Komut satırında şöyle kontrol edilir:

node bin/archify.mjs validate architecture path/to/diagram.json \
  --repo-root path/to/repository --quality showcase --json
# Git geçmişi, commit ve satır aralığı doğrulanır

Bu ayrım önemli: Diyagram teknik olarak “doğru çizilmiş” olabilir ama anlattığı sistem hâlâ yanlış olabilir. Biri “resim düzgün mü?” sorusu, diğeri “resim gerçeği anlatıyor mu?” sorusu. İkisini ayrı tutmak gerek.

Büyüt

Kontrol ve düzeltme — 9 adımda güvenlik

Önizleme (render) hızlı bir taslak; asıl güvenlik kapısı “teslim” (deliver). Program 9 kontrolden geçmeden dosyayı değiştirmiyor — eski iyi dosyanın üzerine yazmıyor. Videolardan birinde bilerek hatalı bir örnek denendi: olmayan bir kişiye mesaj gönderen sıralı diyagram. Sistem reddetti ve önceki doğru dosya olduğu gibi kaldı. Hata mesajı “bilinmeyen hedef” dedi ama her zaman tam çözüm tarifi vermiyor — bazen sadece sorunu söylüyor.

9 kontrol nedir, basitçe? Yazı sığıyor mu (92 piksele 102 piksellik yazı sığmaz), ok kutunun içinden geçiyor mu, çizgi yazının üstünden geçiyor mu, boşluklar yeterli mi, ekran taşıyor mu (1440×900 dahil 4 boyutta). Hepsi "teslim" (deliver) kapısında bakılır; biri bile hatalıysa dosya değişmez, eski doğru dosya kalır ve sistem "şurada hata var" der.

Gerçek düzeltme: Başlık kutuya sığmamışsa program "sığmıyor" der, yapay zeka kutuyu 92'den 132 piksele büyütür — yazıyı küçültmeden, sadece kutuyu genişleterek. 2 denemede düzelir.

Bu 9 kontrol; çizgilerin düzgünlüğü, yazıların çakışmaması, okların kutuların içinden geçmemesi gibi şeylere bakıyor. Ayrı bir kontrol de tarayıcıda taşma var mı diye bakıyor (1440×900 dahil 4 ekranda). İlk denemede resim 1209 piksel olup taşmış, boşluklar azaltılıp 900’e çekilmiş. Yani sadece “kod doğru mu?” değil, “ekranda düzgün görünüyor mu?” da kontrol ediliyor.

node bin/archify.mjs validate architecture examples/web-app.architecture.json --quality showcase --json
node bin/archify.mjs deliver architecture source.json --out out/arch.html --quality showcase --json
# ikisi de geçerse: { sourceHash, outputHash, checks: "9/9" } — imzalı makbuz gibi

Videolarda iki düzeltme örneği net: Birinde başlık kutunun üstüne binmiş, diğerinde etiket sığmamış. Yapay zeka her seferinde küçük bir düzeltme yapıp tekrar denemiş ve 2 denemede geçmiş. Önemli olan hatanın net söylenmesi.

Büyüt

Paylaşma, tema ve PR'da farkı görme

Ortaya çıkan dosya tek bir HTML. İnternet olmadan da açılıyor, mail’e ekleyip gönderebiliyorsun, PR yorumuna bırakabiliyorsun. Yanında küçük bir makbuz geliyor: “bu liste şu hash’ten, bu resim şu hash’ten üretildi” diye.

Tek HTML ne demek? Bütün resim ve yazı tek dosyada; internet olmadan çift tıklayıp açılır, e-postaya eklenir, PR (Pull Request — kod değişikliğini ekipçe gözden geçirme) yorumuna yapıştırılır. Yanında küçük makbuz (hash — dosyanın parmak izi) gelir: "bu liste şu parmak izinden, bu resim şu parmak izinden üretildi" — sonra kim değiştirdi, iz sürülür. Tema (classic/blueprint/editorial) sadece renkleri değiştirir, kutuların yeri aynı kalır.

İçinde neler var? Kutularda arama, bir kutuya odaklanma, “öncesi/sonrası” iz sürme, adım adım anlatım. Hareket (trace) normalde kapalı — video için açarsan oklar akıyor ama anlam değişmiyor, sadece anlatımı kolaylaştırıyor.

Dışa aktarma seçenekleri: PNG / JPEG / WebP (4 kata kadar net), SVG (koyu/açık temayı aynı dosyada taşır), WebM (hareketli), 1200×630 paylaşım kartı, panoya kopyala. SVG’yi doğrudan GitHub README’ye koymak mümkün.

Çevrimdışı test edilmiş: İnternet kapalıyken bile açıldı, arama çalıştı, tema değişti, SVG indirme hatasız çalıştı. Google Fonts kapalı kalsa bile bozulmuyor.

En güçlü özellik PR incelemesi için: Öncesi / Fark / Sonrası . İki doğru diyagramı karşılaştırıp “şu 2 kutu eklendi, 1’i silindi, 1’i taşındı, 2 bağlantı yön değiştirdi” diye net bir liste veriyor. Statik bir resme bakmak yerine “ne değişti?”yi görüyorsun. Not: Bu liste sadece senin yazdığın şeylerin farkını gösterir; canlı sistemin etkisini veya “birleştirince patlar mı?” sorusunu cevaplamaz.

Büyüt

İyi sonuç için 6 basit kural

• Tek soru, tek resim. “Cache yokken ne oluyor?” net bir soru; “her şeyi çiz” bulanık.
• 8–12 kutu. Daha fazlası haritayı değil, karışıklığı büyütür.
• Kanıt iste. “Sadece gerçekten var olanı çiz, kanıtlayamazsan ekleme, SRC ekle.”
• Düzeltmeye izin ver. İlk denemede hata normal — sistem söyler, yapay zeka düzeltir.
• Listeyi sakla. Kurallı listeyi (JSON) projeye commit et; bir sonraki sefer düzenlemesi kolay olur.
• Dışa aktarımı kontrol et. PNG/SVG’yi alıp yazı okunuyor mu, renkler solmuyor mu bak.

# iyi soru (sınırlı)
Use archify to explain an API cache miss with a browser, an API, Redis, and PostgreSQL
and show the return calls. Validate with showcase and keep source + receipt.

# kötü soru (sınırsız)
Map everything in this huge repo.
# → güzel görünen ama boş bir resim

Neleri yapmaz? Sınırları bil

Archify sana hazır bir paylaşım sitesi vermez, serbest çizim programı değildir. Mermaid metnini okuyup yeni bir liste yazabilir ama “Mermaid’i otomatik çeviririm” garantisi yok. Çizilen ok, canlı trafik var demek değil. Canlı sistemi kendi kendine keşfetmez, “bu PR birleştirilebilir” demez — sadece senin yazdığın listeyi kontrol eder.

Ne yapmaz, net: Kodunuzu düzeltmez, yeni özellik yazmaz, veritabanını bağlamaz. Sadece "ne var ve nasıl bağlı?" sorusunu resme döker. Resim doğru çizilmiş olsa bile anlattığı sistem yanlış olabilir — "resim düzgün" ≠ "sistem doğru". İkisini ayrı kontrol etmek gerekir. 50 dosyanın hepsini tek resme sığdırmaya çalışmak da yapmaz; insan gözü 12 kutudan fazlasını takip edemez.

6 kural, ezber için: 1) Tek soru tek resim, 2) 8–12 kutu, fazlası çorba, 3) "Sadece gerçek olanı çiz, kanıt yoksa ekleme", 4) Hata normaldir — sistem söyler, düzelt, 5) Listeyi (JSON) projeye kaydet, 6) Dışa aktardıktan sonra yazı okunuyor mu, renk solmuyor mu kontrol et. Bu 6'sı videolarda en çok tekrarlanan cümledir.

README içinde küçük bir şema lazımsa GitHub’ın kendi Mermaid desteği daha pratik olabilir; Archify’ın HTML’i README’de doğrudan görünmez, resim olarak dışa aktarman gerekir. Ayrıca liste teknik olarak doğru olsa bile anlattığın sistem yanlış olabilir — yapay zeka kurallara uygun ama hatalı bir liste yazabilir. O yüzden son bir insan gözü şart.

Ücret, lisans ve nerede denemeli

Archify MIT lisanslı, ücretsiz ve açık kaynak. Resim için abonelik yok. Ücret, kullandığın yapay zeka modelinden gelir; aynı anda çok ajan çalıştırırsan kullanım artar. Videolarda da söylendiği gibi: Önce tek, net bir diyagramla başla; gerçekten ayrı soruların (harita + sıralı adımlar + iş akışı) varsa paralel dene.

Ücret ve deneme: Açık kaynak, bilgisayarınızda çalışır; çizim için dış servise dosyanız gitmez. 2 dakikalık deneme: npx skills add tt-a1i/archify -g → node bin/archify.mjs doctor ile "hazır" gör → Archify dosyalarını aç → en basit soruyla başla: "Bu repo nedir, 5 cümlede ve basit haritayla anlat."

Önerilen deneme: Tek bir ekipte, en çok ihmal edilmiş serviste, 2 hafta boyunca Öncesi/Fark/Sonrası ile PR incelemesi yap. İki şeye bak: Bu kontroller gerçekten yapay zekanın sessizce geçireceği hataları yakalıyor mu? Gecikme rahatsız ediyor mu? Canlı çalışırken ağır gelirse sadece birleştirmeden önceki kontrole koy; tek dosya HTML ile paylaşma yolunu ise hemen kullanabilirsin.

7 videoyu + Exa’dan çektiğim resmi belgeleri yan yana koyduğumda şunu görüyorum: Teknik iddia abartı değil. Liste → kontrol → çizim zinciri gerçekten var ve düzeltme döngüsü çalışıyor. Yıldız sayılarının videodan videoya 44 bin ile 7,4 bin arasında değişmesi ise projenin ne kadar hızlı güncellendiğini gösteriyor; v2.12 / v2.15 / 2.16 / 2.17 etiketleri aynı hafta içinde geçiyor.

Karşı görüşü de hakkını vererek söyleyeyim: Mermaid ve PlantUML yıllardır var, ekosistemleri çok büyük. Archify’ın “kontrol ediyorum” dediği şey, yapay zekanın yazdığı listeyi kontrol etmek — gerçek sistemle uyumu hâlâ senin bakışına kalıyor. Videolardaki karşılaştırmalar da projenin kendi sayfasından geliyor; bağımsız, tarafsız bir test yok.

Benim pratik kararım: Özellikle hızlı kodlanmış (vibe-coded) projelerde “gerçekten ne inşa ettik?” sorusuna ilk dürüst haritayı Archify veriyor. Ama README içinde küçük bir şema, resmi bir belge zorunluluğu veya hiç yapay zeka kullanmayan bir ekip için Mermaid/Structurizr hâlâ daha mantıklı. Kural basit: “Tek soru, 8–12 kutu, kanıtlı SRC”ye uyarsan sonuç kalıyor; kuralı esnetirsen güzel ama yanlış bir resmin oluyor.