tt-a1i/archify
Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
Hızlı değerlendirme
Özet
Archify, coding agent’lara açıklamalardan veya repository içeriğinden etkileşimli mimari ve sistem diyagramları ürettiren bir agent skill’dir.
Profiline uyum
Agent'larla mimari ve akış diyagramları üretmesi, RAG ve agent sistemleri geliştirme çalışmalarınıza dolaylı destek sağlayabilir.
Neden yükseliyor
166 günlük yaşına göre 72.324 yıldız ve son 28 günde 84 commit ile 27 farklı yazar güçlü görünürlük ve yakın dönem katkı sinyali veriyor. Agent ekosistemindeki yaygın araçlarla entegrasyon ve etkileşimli demo galerisi ilgiyi destekliyor; yıldız sayısı tek başına kullanım veya kalite kanıtı değil.
Problem
Mimari ve akış diyagramlarını elle hazırlamak zaman alır; statik diyagramlar da sistemi keşfetmek ve başkalarına anlatmak için sınırlı kalabilir.
Çözüm
Cursor, Claude Code, Codex CLI ve OpenCode gibi agent’lara eklenen bir skill olarak doğal dildeki isteği self-contained, etkileşimli HTML çıktısına dönüştürür. README; architecture, workflow, sequence, data-flow ve lifecycle diyagramlarını desteklediğini, repository okunarak kaynakla ilişkilendirilmiş diyagramlar üretilebildiğini belirtiyor.
Yenilik
Doğal dilden diyagram üretimi yeni bir fikir değil; Archify’nin belirgin yönü bunu farklı coding agent’lara eklenebilen bir skill üzerinden, keşfedilebilir etkileşim ve self-contained HTML çıktısıyla sunması. README bu çıktıların doğruluk veya kaynakla tutarlılık oranına dair ölçüm vermiyor.
Teknolojiler
- JavaScript
- HTML
- coding agents
- npx skills
Riskler
- Agent’ın oluşturduğu diyagramdaki bileşenler ve bağlantılar hatalı ya da eksik olabilir; özellikle mimari kararlar için çıktının kaynak kod ve sistem bilgisiyle doğrulanması gerekir.
- Çıktı kalitesi, kullanılan agent’ın ve isteğin niteliğine bağlı olabilir; farklı agent’lar arasında eşdeğer sonuç verildiğine dair ölçüm paylaşılmamış.
- Etkileşimli HTML çıktılarının ekip içi bakım, sürümleme ve güncelleme süreci README kesitinde net değil.
- Yüksek yıldız sayısı benimseme ve uzun dönemli sürdürülebilirliği tek başına göstermez.
Detaylı değerlendirme
Uyum profiline göre: bu işime yarar mı?
Ne yapar
Archify, bir sistem veya codebase açıklamasını agent üzerinden beş tür etkileşimli diyagrama dönüştürür: Architecture, Workflow, Sequence, Data Flow ve Lifecycle. Agent, typed JSON IR üretir; Archify bunu deterministic olarak doğrulanmış self-contained HTML/SVG çıktısına çevirir. Çıktı PNG, SVG, WebM ve 1200×630 share card olarak export edilebilir. Ayrıca iki doğrulanmış snapshot arasında Before / Delta / After karşılaştırması yapabilir; eklenen, silinen, değişen, taşınan ve yeniden yönlendirilen authored facts listesini gösterir.
Nasıl çalışır
Archify bir Node.js CLI ve agent skill olarak çalışır. Kullanıcı chat içinde sistem tanımı veya repository verir; agent, Archify'nin schema'sına uygun JSON IR üretir. Schema, layout, HTML/SVG, route ve label-to-route clearance validator'ları çalıştırılır. Tüm kontroller geçmeden son artifact'in üzerine yazılmaz; hata durumunda stable rule codes, ölçümler ve desteklenen düzeltmeler içeren JSON diagnostics döner. Viewer, authored node ve relationship verisini kullanarak search, upstream/downstream reach, route probe, semantic lens, guided story ve snapshot comparison sunar. `preview` modu yalnızca loopback üzerinde tek bir JSON dosyasını izler ve geçersiz değişikliklerde last-good çıktıyı korur. Kaynak kanıtı istenirse belirli bir public commit'e ve dosya satır aralıklarına bağlanabilir; live infrastructure incelemesi yapmaz.
Kullanım alanları
- Kaliwa ürünlerinin Architecture ve runtime tasarımını README veya teknik tasarım dokümanına eklemek
- Supabase Edge Functions, PostgreSQL, Vercel, Anthropic ve RAG bileşenlerinin veri akışını görselleştirmek
- PR öncesinde bir mimari değişikliğin Before / Delta / After farkını incelemek
- Agent workflow, tool call, approval, retry ve rollback akışlarını Sequence veya Workflow diyagramı olarak anlatmak
- Onboarding, incident review ve design review sırasında tek dosyalık, paylaşılabilir diyagram artifact'i üretmek
Alternatifler
- Mermaid
- D2
- Structurizr DSL
Kimler için
Architecture ve system design dokümantasyonu hazırlayan yazılım ekipleri, agent kullanan geliştiriciler ve PR/design review yapan teknik ekipler için. Özellikle diyagramı chat içinden üretmek ve çıktıyı tekrar üretilebilir bir JSON kaynağıyla version-control altında tutmak isteyen ekipler için uygun.
Olgunluk
Beta. 53.332 star, son 28 günde 92 commit, 15 farklı yazar ve 18 sürüm güçlü ilgi ve aktif geliştirmeye işaret ediyor. Ancak proje yalnızca 146 günlük; README'de kullanılan sürüm `2.17.0-dev.1` olarak belirtilmiş. Validation ve last-good workflow gibi üretim güvenilirliği hedefleyen mekanizmalar var, fakat bu veriler uzun dönem production stability kanıtı değil.
Kurulum
Denemesi düşük-orta zahmetli. En kısa yol `npx skills add tt-a1i/archify -g`; Codex CLI, Claude Code, Cursor ve opencode için kurulum seçenekleri bulunuyor. Repository olmadan chat içindeki bir sistem açıklamasıyla başlanabiliyor. Daha kontrollü kullanımda repository içinden `node bin/archify.mjs doctor`, `validate`, `preview` ve `deliver` komutları çalıştırılıyor. Node.js gerektiriyor; README'deki DeepSeek Harness integration için ayrıca Node `^22.19.0 || >=24.0.0` şartı var. Kaliwa'nın Deno/Edge Functions runtime'ına kurulması gerekmiyor; bu bir geliştirme ve dokümantasyon aracı olarak ayrı çalışır.
Bizim için
Somut kullanım
Kaliwa repository'sinde bir `docs/architecture/` veya `docs/diagrams/` alanı oluşturulup JSON IR kaynakları commit edilebilir. Örneğin `web-app` Architecture diyagramında Next.js frontend, Vercel, Supabase Auth, Edge Functions, PostgreSQL, pgvector, RAG retrieval ve Anthropic çağrılarını; Data Flow diyagramında kullanıcı verisinin embedding ve retrieval yolunu; Workflow diyagramında bir AI agent'in tool call, validation, retry ve failure akışını gösterebiliriz. Her mimari PR'sinde Before / Delta / After karşılaştırması çalıştırılabilir. Bununla birlikte Archify'yi Kaliwa production request path'ine veya Supabase Edge Functions içine koymak için somut bir gerekçe yok.
Uyum gerekçesi
Kaliwa'nın agent, coding-agent, architecture-as-code ve LLM tabanlı geliştirme pratiğiyle doğrudan örtüşüyor. TypeScript/JavaScript ekosistemine ve CLI tabanlı geliştirmeye yakın; ürettiği self-contained HTML artifact'leri Vercel veya statik dokümantasyon üzerinden paylaşmak mümkün. Ancak Next.js/React uygulamasına gömülen bir library değil, Supabase/PostgreSQL/pgvector veya Anthropic ile doğrudan entegrasyonu yok ve Node.js gerektiriyor. Bu nedenle ürün runtime'ına katkısı düşük, fakat architecture documentation ve design review için uyumu yüksek.
Engeller
- Node.js tabanlı; Kaliwa'nın background runtime'ı Deno olsa da bu aracı ayrı bir development dependency olarak çalıştırmak gerekir.
- README'de production stability kanıtı yerine `dev` sürüm belirtiliyor; hızlı değişen schema ve CLI davranışları olabilir.
- Agent çıktısının doğrulanması topology'nin doğru olduğu anlamına gelmez; source evidence istenmediğinde diyagram kullanıcı/agent açıklamasına dayanır.
- Mevcut Mermaid parsing, hosted sharing ve WYSIWYG editing kapsam dışında.
- Agent integration'ları için Cursor, Claude Code, Codex CLI ve opencode gibi belirli yüzeylere bağlı; Kaliwa'nın kendi agent orchestration katmanına doğrudan SDK/API entegrasyonu gösterilmiyor.
- Diyagram kaynaklarını ve üretilen HTML çıktısını repository'de nasıl version-control edeceğimiz için ekip içi bir convention belirlemek gerekir.
Ne zaman kullanılır
Bir sistemin bileşenleri ve ilişkileri hakkında insan tarafından okunabilir, paylaşılabilir ve source-controlled bir artifact gerektiğinde kullanılmalı. Özellikle Kaliwa'da `Next.js -> Supabase Edge Functions -> PostgreSQL/pgvector -> Anthropic` gibi sınırları, veri akışını ve agent tool çağrılarını tasarım aşamasında netleştirmek için değerli. PR sırasında iki JSON snapshot'ını karşılaştırarak mimari değişiklikleri görsel ve makine-okunabilir biçimde incelemek de anlamlı bir kullanım.
Ne zaman kullanılmaz
Üretim telemetry'sinden otomatik ve gerçeğe dayalı runtime topology çıkarmak, live infrastructure'ı keşfetmek veya gerçek trafik/performans etkisi hakkında sonuç üretmek için kullanılmamalı; README açıkça live infrastructure incelemediğini ve interaction'ların runtime impact iddiasında bulunmadığını söylüyor. WYSIWYG bir diagram editor, hosted sharing platformu veya mevcut Mermaid diyagramlarını otomatik parse eden migration aracı arıyorsanız uygun değil. Basit bir README diyagramı için Archify'nin agent ve validation katmanı gereksiz olabilir.
Dikkat edilecekler
- İlk denemede küçük bir gerçek Kaliwa akışıyla başlayın: örneğin Next.js -> Edge Function -> PostgreSQL -> Anthropic/RAG yolu.
- Agent'in uydurduğu bileşenleri önlemek için repository analysis ve source evidence akışını kullanın; yalnızca serbest metin açıklamasıyla üretilen diyagramı gerçek topology kanıtı saymayın.
- JSON IR'ı asıl kaynak olarak commit edin; generated HTML'yi release veya docs artifact'i olarak değerlendirin.
- `validate --json` çıktısını CI'da çalıştırmayı ancak schema ve CLI sürümü sabitlendikten sonra düşünün.
- Archify'nin route/reach interaction'ları authored relationships üzerinden çalışır; bunları gerçek runtime metrics, dependency tracing veya security boundary kanıtı olarak yorumlamayın.
- MIT lisansı benimseme açısından düşük riskli, ancak sponsor, update check ve kullanılan Agent yüzeylerinin network davranışını ekip politikalarıyla kontrol edin.