Mermaid Architect: Keterampilan Diagram & Dokumentasi

Arsitek Putri Duyung - Skill Diagram & Dokumentasi Komprehensif

Versi 2.0 - Arsitektur hierarkis dengan orkestrasi cerdas

Skill Claude Code yang andal untuk membuat diagram Putri Duyung dan dokumen desain menggunakan pemuatan panduan sesuai permintaan, pembuatan kode-ke-diagram, dan utilitas Python.

Instalasi

Instal Sekali Klik melalui Pasar Skilz

Instal skill ini secara instan dari Pasar Skilz:

skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid

Instalasi Manual

Kloning langsung ke direktori skill Claude Code Anda:

# Arahkan ke direktori skill Anda
cd ~/.claude/skills

# Kloning repositori
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git

Verifikasi Instalasi

Setelah instalasi, verifikasi bahwa skill tersedia:

# Daftar skill yang terinstal
ls ~/.claude/skills/design-doc-mermaid

# Atau tanyakan Claude Code
# "Daftar skill saya yang terinstal"

Apa yang Dilakukan Skill Ini

Pembuatan Diagram Cerdas:

• Diagram aktivitas (alur kerja, proses, logika bisnis)
• Diagram deployment (infrastruktur cloud, K8s, serverless)
• Diagram arsitektur (komponen sistem, layanan mikro)
• Diagram urutan (alur API, interaksi layanan)
• Dokumen desain lengkap dengan diagram tertanam

Konversi Kode-ke-Diagram:

• Ekstrak arsitektur dari aplikasi Spring Boot
• Hasilkan diagram deployment dari file konfigurasi
• Buat diagram urutan dari panggilan metode
• Dokumentasikan pipeline ETL dan aliran data

Manajemen Diagram:

• Ekstrak diagram Putri Duyung dari file Markdown
• Validasi sintaks diagram dengan mermaid-cli
• Konversi diagram ke gambar PNG/SVG
• Proses batch seluruh direktori

Mulai Cepat

Buat Diagram Aktivitas

Pengguna: "Buat diagram aktivitas untuk pendaftaran pengguna dengan verifikasi email"

Skill akan:

1. Muat references/guides/diagrams/activity-diagrams.md
2. Gunakan template pola pendaftaran
3. Tambahkan simbol Unicode (🔐 untuk keamanan, 📧 untuk email, ✅ untuk sukses)
4. Terapkan gaya kontras tinggi
5. Keluarkan diagram Putri Duyung lengkap

Hasilkan dari Kode

Pengguna: "Ini application.yml Spring Boot saya - buat diagram deployment"

Skill akan:

1. Analisis konfigurasi (sumber data, cache, keamanan)
2. Muat references/guides/diagrams/deployment-diagrams.md
3. Muat examples/spring-boot/README.md
4. Petakan konfigurasi ke sumber daya cloud
5. Hasilkan diagram deployment dengan spesifikasi sumber daya

Buat Dokumen Desain

Pengguna: "Buat dokumen desain API untuk API kontak"

Skill akan:

1. Muat assets/api-design-template.md
2. Muat panduan diagram yang relevan (urutan, ER, arsitektur)
3. Hasilkan dokumen lengkap dengan diagram tertanam
4. Simpan ke docs/design/api-contacts-v1-2025-01-13.md

Struktur

Organisasi Hierarkis

mermaid-architect/
├── SKILL.md                          # Orkestrator utama dengan pohon keputusan
├── README.md                         # File ini
├── CLAUDE.md                         # Instruksi Claude Code
│
├── references/                       # Bahan referensi
│   ├── mermaid-diagram-guide.md     # Panduan umum warisan
│   └── guides/                       # Panduan khusus (muat sesuai permintaan)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # ✅ Selesai
│       │   ├── deployment-diagrams.md    # ✅ Selesai
│       │   ├── architecture-diagrams.md  # ✅ Selesai
│       │   └── sequence-diagrams.md      # ✅ Selesai
│       ├── code-to-diagram/
│       │   └── README.md                 # ✅ Selesai (panduan utama)
│       ├── unicode-symbols/
│       │   └── guide.md                  # ✅ Selesai (100+ simbol)
│       └── troubleshooting.md        # ✅ Selesai (28 kesalahan umum)
│
├── scripts/                          # Utilitas Python
│   ├── extract_mermaid.py           # ✅ Ekstrak & validasi diagram
│   └── mermaid_to_image.py          # ✅ Konversi ke PNG/SVG
│
├── examples/                         # Pola spesifik bahasa
│   ├── spring-boot/                 # ✅ Selesai
│   ├── fastapi/                     # ✅ Selesai
│   ├── react/                       # ✅ Selesai
│   ├── python-etl/                  # ✅ Selesai
│   ├── node-webapp/                 # ✅ Selesai
│   └── java-webapp/                 # ✅ Selesai
│
└── assets/                           # Template dokumen desain
    ├── architecture-design-template.md
    ├── api-design-template.md
    ├── feature-design-template.md
    ├── database-design-template.md
    └── system-design-template.md

Fitur Utama

1. Simbol Semantik Unicode

Setiap diagram menggunakan simbol Unicode yang bermakna:

graph TB
    User[👤 Client] --> Gateway[🌐 API Gateway]
    Gateway --> Auth[🔐 Auth Service]
    Gateway --> API[⚙️ API Service]
    API --> DB[(💾 Database)]
    API --> Cache[(⚡ Redis)]
    API --> Queue[📬 Message Queue]
    Queue --> Worker[⚙️ Background Worker]

Kategori Simbol:

• Infrastruktur: ☁️ 🌐 🔌 📡 🗄️
• Komputasi: ⚙️ ⚡ 🔄 🚀 💨
• Data: 💾 📦 📊 📈 🗃️
• Pesan: 📨 📬 📤 📥 🐰
• Keamanan: 🔐 🔑 🛡️ 🚪 👤
• Pemantauan: 📝 📊 🚨 ⚠️ ✅ ❌

2. Gaya Kontras Tinggi

Semua diagram menggunakan warna yang mudah diakses dan kontras tinggi - lihat SKILL.md untuk detail lengkap.

3. Utilitas Python

Ekstrak Diagram

# Daftar semua diagram dalam file
python scripts/extract_mermaid.py document.md --list-only

# Ekstrak ke file .mmd terpisah
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Validasi semua diagram
python scripts/extract_mermaid.py document.md --validate

# Ganti diagram dengan referensi gambar (untuk Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

Konversi ke Gambar

# File tunggal
python scripts/mermaid_to_image.py diagram.mmd output.png

# Tema dan ukuran kustom
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Konversi batch direktori
python scripts/mermaid_to_image.py diagrams/ output/ \
  --format png --recursive

# Dari stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png

Persyaratan

Untuk Pembuatan Diagram

• Sistem skill Claude Code (otomatis)
• Panduan dan template (termasuk dalam skill ini)

Untuk Validasi & Konversi Gambar

# Instal mermaid-cli secara global
npm install -g @mermaid-js/mermaid-cli

# Verifikasi instalasi
mmdc --version

Untuk Skrip Python

• Python 3.7+
• Tidak diperlukan paket tambahan (hanya menggunakan stdlib)

Jalur Pembelajaran

Baru dengan Diagram Putri Duyung?

1. Mulai dengan Diagram Aktivitas - Baca references/guides/diagrams/activity-diagrams.md
2. Pelajari Simbol Unicode - Baca references/guides/unicode-symbols/guide.md
3. Coba Contoh - Gunakan pola dari examples/spring-boot/
4. Validasi Hasil Kerja Anda - Jalankan python scripts/extract_mermaid.py --validate

Perlu Mendokumentasikan Kode yang Ada?

1. Identifikasi Framework - Spring Boot, FastAPI, React, dll.
2. Muat Panduan Contoh - Baca examples/{your-framework}/README.md
3. Cocokkan Pola - Temukan pola kode serupa di contoh
4. Hasilkan Diagram - Gunakan template dari panduan
5. Validasi - Gunakan skrip validasi

Membuat Dokumen Desain?

1. Pilih Tipe Template - Arsitektur, API, Fitur, Database, atau Sistem
2. Muat Template - Baca dari assets/{type}-design-template.md
3. Isi Bagian - Ganti placeholder dengan konten aktual
4. Tambahkan Diagram - Muat panduan diagram sesuai kebutuhan untuk setiap bagian
5. Gunakan Simbol - Perkaya dengan simbol Unicode di seluruh
6. Simpan - Tempatkan di docs/design/ dengan stempel waktu

Cara Kerja Sistem Hierarkis

Pendekatan Tradisional (Tidak Efisien)

• Muat seluruh dokumentasi skill (~50KB)
• AI memproses semua template dan contoh
• Penggunaan token tinggi
• Waktu respons lambat

Pendekatan Hierarkis (Efisien)

1. Pengguna membuat permintaan → AI menganalisis maksud
2. Pohon keputusan aktif → Menentukan panduan yang dibutuhkan
3. Muat hanya yang dibutuhkan → Membaca panduan spesifik (~2-5KB)
4. Hasilkan keluaran → Menggunakan template yang ditargetkan
5. Efisien token → 10x lebih sedikit konteks yang dibutuhkan

Alur Contoh

Pengguna: "Buat diagram deployment untuk pengaturan Docker Compose saya"

Pohon Keputusan:

1. Analisis: "diagram deployment" + "Docker Compose"
2. Tentukan: deployment-diagrams.md dibutuhkan
3. Muat: references/guides/diagrams/deployment-diagrams.md (2KB)
4. Temukan pola: template Docker Compose ada
5. Hasilkan: Menggunakan template + simbol Unicode
6. Keluaran: Diagram lengkap dalam <30 detik

Token Digunakan: ~2.000 (vs ~10.000 dengan pendekatan tradisional)

Status Penyelesaian

✅ Selesai:

• Orkestrator pohon keputusan hierarkis
• Panduan diagram aktivitas dengan template
• Panduan diagram deployment (AWS, GCP, K8s, serverless, Docker)
• Panduan simbol Unicode (100+ simbol)
• Skrip ekstrak Putri Duyung dengan validasi
• Skrip konversi Putri Duyung ke gambar
• Contoh kode-ke-diagram Spring Boot
• Template dokumen desain (5 tipe)
• Sistem gaya kontras tinggi

🚧 Dalam Progres:

• Contoh FastAPI
• Contoh arsitektur komponen React
• Contoh pipeline ETL Python

📋 Direncanakan:

• Panduan diagram arsitektur
• Panduan diagram urutan
• Panduan utama kode-ke-diagram
• Contoh Node.js/Express
• Contoh aplikasi web Java

Berkontribusi

Untuk menambahkan panduan tipe diagram baru:

1. Buat panduan di references/guides/diagrams/{type}-diagrams.md
2. Sertakan:
   • Kapan digunakan
   • Sintaks dasar
   • Pola umum (3-5 template)
   • Contoh simbol Unicode
   • Praktik terbaik
3. Perbarui pohon keputusan SKILL.md
4. Tambahkan contoh dengan pemetaan kode

Untuk menambahkan contoh bahasa baru:

1. Buat direktori di examples/{framework}/
2. Tambahkan README.md dengan:
   • Ikhtisar framework
   • Diagram arsitektur dari struktur
   • Diagram deployment dari konfigurasi
   • Diagram urutan dari kode
   • Diagram aktivitas dari logika
3. Perbarui tabel kode-ke-diagram SKILL.md

Lisensi

Bagian dari Claude Code Skills - Lisensi MIT

Skill Terkait

• confluence - Unggah diagram ke Confluence
• plantuml - Format diagram alternatif

Tautan

• Repositori GitHub
• Daftar Pasar Skilz
• Dokumentasi Resmi Putri Duyung

Versi: 2.0.0 Diperbarui: 2025-01-13 Dikelola oleh: SpillwaveSolutions