What is Archify? Turn Your Code into Clear Diagrams

Why do we need such a tool?

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.

Plain words: A diagram is like the wiring plan of a building — you see at a glance where each socket connects. If AI draws without a plan, the wiring is wrong and no one notices. Archify first writes a checkable list (JSON) and checks it line by line; the picture comes last.

Analogy: Trying to cook an omelette without writing "3 eggs" in the recipe — without measures the result is luck.

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.

Install — one line, 30 seconds

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.

What is Node 18? The program that runs JavaScript on your computer. Version 18 is already on any computer from the last 2–3 years; no graphics card needed. npx skills add tt-a1i/archify -g means "add this skill to my AI tool so I can use it in any project" (-g = global).

If stuck: Tell your AI: "Load the skill from GitHub tt-a1i/archify" — that sentence almost always works in Cursor.

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.

Enlarge

5 diagram types — which one to use when?

Ö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:

Which question → which type? "What exists?" → map (architecture), "In which order?" → steps (sequence), "Who approves?" → workflow, "Where does data go?" → data journey, "How does state change?" → state. Picking the wrong type is like reading a road map from a building plan.

Kısa kural: “Neler var?” → harita, “Sırayla on cache miss?” → 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.

Enlarge

What happens behind the scenes? (simply)

Hiç kod bilmeden şöyle düşün: Yapay zekaya “çiz” demek yerine “maddeler halinde listele” diyorsun. Örneğin: “Browser 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.

Kid-simple: Instead of saying "draw", you say "first describe in 4 sentences, then draw from those sentences." If a sentence has a typo the teacher returns the paper. Archify does the same — the program returns the AI's list if it breaks a rule; layout (where boxes go) is computed by the program, so text never overlaps.

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.

Enlarge

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": [ ]
}

First diagram: “cache miss” example

Videolarda en çok gösterilen örnek bu: Browser → API → Redis (fast cache) → Postgres (main DB). Soru net: “Cache’de yoksa on cache miss?” 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.

Everyday picture: A counter — customer asks (browser), clerk first checks the quick drawer (Redis — fast memory), if missing goes to the storage room (Postgres — main database), copies one to the drawer, hands it to the customer. Next time the same question is instant from the drawer. Ask Archify "what happens on cache miss?" and you get those 4 steps in one picture.

Golden rule: One picture = one question, at most 8–12 boxes, one main path. "Draw everything" is like squeezing kitchen, storage and cash register onto one sheet — unreadable.

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, prooflayamıyorsan ekleme, sonunda single file ver.” 7 videonun 4’ünde neredeyse aynı cümle var — tesadüf değil, işe yaradığı için tekrarlanıyor.

Enlarge

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.

Mapping real code: React Native example

İ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 in one line: One codebase for both iPhone and Android. Archify takes "How does React Native work?" and splits it into 9 parts — Hermes (fast JS engine), Turbo Modules (ready pieces), Shadow Tree (screen tree) — and draws "who connects to whom." In presentation mode you can play it slide by slide or isolate one box.

What is the SRC badge? A small "SRC" on a box means that piece was truly found in code and proven with commit + line number. No badge = the idea is plausible but unproven. In a real repo you say "only draw what is proven."

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 prooflanmış demektir. Rozet yoksa, o kutu ne kadar mantıklı görünse de proofı 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.

Enlarge

Check and repair — 9-step safety

Ö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.

What are the 9 checks, simply? Does text fit (102 px text does not fit 92 px box), does an arrow cut through a box, does a line cross text, is spacing enough, does it overflow the screen (checked at 4 sizes including 1440×900). All are checked at the "deliver" gate; if one fails the file is not overwritten and the system says "fix here."

Real fix: If a title does not fit, the program says "does not fit," the AI widens the box from 92 to 132 px — without shrinking the text. Fixed in 2 tries.

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.

Enlarge

Sharing, themes and spotting diffs in PRs

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.

One HTML means? Everything — text and picture — in one file; opens offline with a double click, attaches to email, pastes into a PR (Pull Request — team review of code changes). A tiny receipt (hash — fingerprint of the file) comes with it: "this list from this fingerprint, this image from that fingerprint" — you can trace who changed what. Theme (classic/blueprint/editorial) only changes colors, positions stay the same.

İçinde what exists? 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.

Enlarge

6 simple rules for good results

• Tek soru, tek resim. “Cache yokken on cache miss?” 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, prooflayamazsan 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

What it doesn't do — know the limits

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.

What it does NOT do, clearly: It does not fix your code, write features, or connect the database. It only turns "what exists and how is it connected?" into a picture. The picture can be well drawn but the system it describes can still be wrong — "picture correct" ≠ "system correct." You cannot fit 50 files into one picture; the eye cannot follow more than 12 boxes.

6 rules to remember: 1) One question one picture, 2) 8–12 boxes, more is soup, 3) "Only draw what exists, no proof → don't add," 4) Error is normal — system tells, you fix, 5) Commit the list (JSON) to the repo, 6) After export check that text is readable and colors not washed out. These 6 are the most repeated sentences in the videos.

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.

Pricing, license and where to try it

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.

Cost and try: Open source, runs on your machine; your files do not go to an external service for drawing. 2-minute try: npx skills add tt-a1i/archify -g → node bin/archify.mjs doctor shows "ready" → open Archify files → start with the simplest question: "What is this repo, in 5 sentences and a simple map."

Ö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; single file 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, prooflı SRC”ye uyarsan sonuç kalıyor; kuralı esnetirsen güzel ama yanlış bir resmin oluyor.