Melampaui Gambar Statis: Membuka Kekuatan Diagram-sebagai-Kode dengan Mermaid dan Alat Berbasis AI
Krisis Dokumentasi
Setiap tim teknik mengetahui rasa sakit ini. Anda menghabiskan berminggu-minggu merancang arsitektur mikroservices yang indah, dengan cermat membuat diagram Visio yang mengesankan para pemangku kepentingan. Enam bulan kemudian, sistem telah berkembang—layanan baru ditambahkan, basis data dipindahkan, endpoint API dinonaktifkan—namun diagramnya membeku dalam waktu. Itu adalah peninggalan. Bahkan, sebuah kebohongan.
Ini adalah “doc-rot” (pelapukan dokumentasi), dan itu adalah pembunuh diam-diam produktivitas teknik. Ketika diagram berbohong, pengembang mengabaikannya. Ketika pengembang mengabaikan dokumentasi, pengetahuan klan (tribal knowledge) mengambil alih. Ketika satu-satunya orang yang mengetahui sistem pergi, Anda ditinggalkan dengan basis kode yang kompleks dan tanpa peta.
Diagram sebagai Kode (DaC) adalah solusinya. Dan di intinya terdapat Mermaid, alat pembuatan diagram berbasis JavaScript yang mengubah teks biasa menjadi visual yang indah.
Filsafat Inti: Perlakukan Diagram Seperti Perangkat Lunak
Perubahan mendasar dengan Diagram sebagai Kode adalah memperlakukan diagram Anda dengan ketelitian yang sama seperti kode aplikasi Anda. Ini berarti:
1. Kontrol Versi adalah Standar
Ketika diagram Anda adalah sebuah file .mermaid, file tersebut berada di repositori Git Anda berdampingan dengan kode sumber Anda. Setiap perubahan dilacak. Anda dapat git blame untuk melihat siapa yang menambahkan layanan baru itu, git diff untuk meninjau perubahan sebelum penggabungan, dan kembali ke keadaan sebelumnya mana pun.
gitGraph
commit id: "Arsitektur awal"
commit id: "Tambah layanan pengguna"
branch feature/order-service
commit id: "Layanan pesanan v1"
commit id: "Tambah gerbang pembayaran"
checkout main
merge feature/order-service
commit id: "Perbarui gerbang API"
Contoh: Memvisualisasikan riwayat Git dari diagram Anda sendiri menggunakan sintaks Git Graph Mermaid
2. Tinjauan Kode untuk Diagram
Permintaan tarik (pull requests) bukan lagi hanya untuk kode. Ketika seorang pengembang mengusulkan layanan baru atau mengubah aliran data, perubahan tersebut muncul sebagai diff yang dapat dibaca dalam PR. Peninjau dapat memberikan komentar pada diagram itu sendiri, memastikan keputusan arsitektur didiskusikan dan disetujui sebelum digabungkan.
3. Integrasi Pipelines CI/CD
Diagram Anda dapat dibuat secara otomatis dan divalidasi dalam pipeline Anda. Bayangkan sebuah Aksi GitHub yang:
-
Merender semua diagram Mermaid sebagai PNG/SVG
-
Mengunggahnya ke situs dokumentasi Anda
-
Gagal membangun jika sintaks Mermaid yang tidak valid terdeteksi
flowchart LR
A[Pengembang Mendorong Kode] --> B[Pipeline CI Berjalan]
B --> C[Jalankan Tes]
B --> D[Render Diagram Mermaid]
D --> E{Sintaks Valid?}
E -->|Ya| F[Upload ke Dokumentasi]
E -->|Tidak| G[Gagal Bangun & Beri Peringatan ke Tim]
F --> H[Deploy Aplikasi]
G --> I[Pengembang Memperbaiki Sintaks]
I --> A
Contoh: Alur kerja CI/CD untuk validasi diagram dan deployment
Mermaid dalam Aksi: Contoh Dunia Nyata
Mari kita jelajahi jenis-jenis diagram yang didukung Mermaid dengan contoh praktis dan dunia nyata.
Contoh 1: Arsitektur Microservices (Flowchart)
Ini adalah kasus penggunaan paling umum—memvisualisasikan bagaimana layanan Anda berkomunikasi.
flowchart TB
subgraph "Lapisan Klien"
MobileApp[Aplikasi Seluler]
WebApp[Aplikasi Web]
end
subgraph "API Gateway"
Gateway[API Gateway]
end
subgraph "Microservices"
UserSvc[Layanan Pengguna]
OrderSvc[Layanan Pesanan]
ProductSvc[Layanan Produk]
PaymentSvc[Layanan Pembayaran]
end
subgraph "Lapisan Data"
UserDB[(Database Pengguna)]
OrderDB[(Database Pesanan)]
ProductDB[(Database Produk)]
Redis[(Cache Redis)]
end
subgraph "Layanan Eksternal"
Stripe[Pembayaran Stripe]
EmailAPI[API Email]
end
MobileApp --> Gateway
WebApp --> Gateway
Gateway --> UserSvc
Gateway --> OrderSvc
Gateway --> ProductSvc
Gateway --> PaymentSvc
UserSvc --> UserDB
UserSvc --> Redis
OrderSvc --> OrderDB
OrderSvc --> Redis
ProductSvc --> ProductDB
ProductSvc --> Redis
PaymentSvc --> Stripe
OrderSvc --> EmailAPI
PaymentSvc --> EmailAPI
Contoh: Arsitektur microservices lengkap dengan caching, database, dan dependensi eksternal
Contoh 2: Alur Autentikasi Pengguna (Diagram Urutan)
Diagram urutan sangat cocok untuk mendokumentasikan interaksi kompleks antar layanan.
sequenceDiagram
autonumber
participant Pengguna
participant Frontend
participant AuthSvc sebagai Layanan Autentikasi
participant UserDB sebagai Database Pengguna
participant Cache sebagai Cache Redis
participant EmailSvc sebagai Layanan Email
Pengguna->>Frontend: Masukkan kredensial
Frontend->>AuthSvc: POST /login (email, password)
AuthSvc->>UserDB: Query pengguna berdasarkan email
UserDB-->>AuthSvc: Kembalikan password terenkripsi & data pengguna
AuthSvc->>AuthSvc: Verifikasi password dengan bcrypt
alt Kredensial Valid
AuthSvc->>AuthSvc: Buat token JWT
AuthSvc->>Cache: Simpan sesi (key: user_id, ttl: 1 jam)
AuthSvc-->>Frontend: 200 OK + token JWT
Frontend-->>Pengguna: Alihkan ke dashboard
else Kredensial Tidak Valid
AuthSvc->>EmailSvc: Pemicu peringatan login gagal
AuthSvc-->>Frontend: 401 Unauthorized
Frontend-->>Pengguna: Tampilkan pesan kesalahan
end
Catatan di atas AuthSvc,EmailSvc: Setelah 5 kali percobaan gagal, kunci akun selama 15 menit
Contoh: Alur autentikasi terperinci yang menunjukkan jalur sukses dan gagal, termasuk efek samping seperti caching dan peringatan
Contoh 3: Infrastruktur Cloud di AWS (Diagram Kelas)
Diagram kelas tidak hanya untuk kode—mereka dapat memodelkan sumber daya cloud dan hubungan antar mereka.
classDiagram
class VPC {
+string cidr_block
+string region
+createSubnet()
+deleteSubnet()
}
class Subnet {
+string availability_zone
+string cidr_block
+boolean is_public
+attachRouteTable()
}
class EC2Instance {
+string instance_type
+string ami_id
+int storage_gb
+start()
+stop()
+reboot()
}
class RDSDatabase {
+string engine
+string version
+int storage_gb
+boolean multi_az
+takeSnapshot()
+restoreFromSnapshot()
}
class S3Bucket {
+string bucket_name
+string region
+boolean versioning_enabled
+uploadFile()
+downloadFile()
}
class IAMRole {
+string role_name
+string policy_document
+attachPolicy()
+detachPolicy()
}
VPC "1" --> "*" Subnet
Subnet "1" --> "*" EC2Instance
Subnet "1" --> "0..1" RDSDatabase
VPC "1" --> "0..*" S3Bucket
EC2Instance --> IAMRole
RDSDatabase --> IAMRole
Contoh: Memodelkan infrastruktur AWS sebagai kelas dengan properti dan metode, berguna untuk dokumentasi dan perencanaan Infrastructure-as-Code
Contoh 4: Pemrosesan Pesanan E-Commerce (Diagram Status)
Diagram status sangat unggul dalam menunjukkan bagaimana entitas beralih melalui berbagai status.
stateDiagram-v2
[*] --> Keranjang: Pengguna menambahkan barang
Keranjang --> Checkout: Pengguna melanjutkan ke pembayaran
Checkout --> PembayaranTertunda: Pengguna mengirimkan pesanan
PembayaranTertunda --> PemrosesanPembayaran: Inisiasi gerbang pembayaran
PemrosesanPembayaran --> Dibayar: Pembayaran berhasil
PemrosesanPembayaran --> GagalPembayaran: Pembayaran ditolak
GagalPembayaran --> Checkout: Pengguna mencoba pembayaran lagi
GagalPembayaran --> [*]: Pengguna meninggalkan keranjang
Dibayar --> PesananDikonfirmasi: Kirim email konfirmasi
PesananDikonfirmasi --> SedangDisiapkan: Ditugaskan ke gudang
SedangDisiapkan --> Terkirim: Serah terima ke kurir
Terkirim --> DalamPerjalanan: Kurir mengambil barang
DalamPerjalanan --> Diterima: Pengiriman dikonfirmasi
Diterima --> PermintaanUlasan: Meminta ulasan pengguna
PermintaanUlasan --> [*]: Pengguna mengirimkan ulasan
Diterima --> PermintaanPengembalian: Pengguna memulai pengembalian dana
PermintaanPengembalian --> PengembalianDisetujui: Dukungan menyetujui
PengembalianDisetujui --> PengembalianDiproses: Uang dikembalikan
PengembalianDiproses --> [*]: Pesanan ditutup
state "Pengecekan Penipuan Berisiko Tinggi" sebagai PengecekanFraud {
[*] --> CekSkor
CekSkor --> RisikoRendah: Skor < 50
CekSkor --> RisikoTinggi: Skor >= 50
RisikoTinggi --> TinjauanManual: Ditandai untuk tim
TinjauanManual --> RisikoRendah: Disetujui
TinjauanManual --> GagalPembayaran: Ditolak
}
PembayaranTertunda --> PengecekanFraud: Penilaian risiko dipicu
PengecekanFraud --> PemrosesanPembayaran: RisikoRendah
Contoh: Mesin keadaan pesanan e-commerce lengkap dengan keadaan terdeteksi penipuan yang bersarang
Contoh 5: Perencanaan Sprint dengan Masalah GitHub (Grafik Git)
Grafik Git dapat merepresentasikan alur kerja di luar Git itu sendiri.
gitGraph
commit id: "Perencanaan Sprint" type: HIGHLIGHT
branch sprint-1
commit id: "Cerita Pengguna #101: Halaman Login"
commit id: "Cerita Pengguna #102: Pendaftaran Pengguna"
branch bugfix/hotfix
commit id: "Perbaikan Cepat: Kedaluwarsa Token Autentikasi"
checkout sprint-1
merge bugfix/hotfix
commit id: "Cerita Pengguna #103: Pengaturan Ulang Kata Sandi"
checkout main
merge sprint-1 tag: "v1.0.0"
branch sprint-2
commit id: "Fitur #201: Keranjang Belanja"
commit id: "Fitur #202: Alur Checkout"
branch experiment/ai-recommendations
commit id: "POC: Mesin Rekomendasi ML"
checkout sprint-2
commit id: "Fitur #203: Riwayat Pesanan"
checkout main
merge sprint-2 tag: "v2.0.0"
commit id: "Catatan Rilis: Sprint 1 & 2 Selesai"
Contoh: Memvisualisasikan manajemen proyek, sprint, dan cabang fitur sebagai grafik Git
Revolusi AI dalam Pembuatan Diagram
Meskipun Mermaid elegan, sintaksnya bisa menjadi hambatan. Siapa yang ingin men-debug panah yang tidak sejajar atau kurung yang hilang saat Anda mencoba mendokumentasikan sebuah sistem?
Di sinilah alat yang didukung AI mengubah segalanya.
Perbaikan Otomatis AI
Alat seperti VPasCode (platform Diagram as Code dari Visual Paradigm) dan Mermaid Chart telah mengintegrasikan model AI (seperti Google Gemini dan OpenAI) yang dapat:
-
Mendeteksi Otomatis kesalahan sintaks
-
Memperbaiki diagram yang rusak dengan satu kali klik
-
Menyarankan perbaikan pada struktur diagram
Mari kita lihat ini dalam aksi:
Kode Mermaid yang Rusak:
flowchart LR
A[Frontend] --> B(API Gateway
B --> C[User Service]
C --> D[(Database
D --> E[Cache]
Kode yang Diperbaiki AI:
flowchart LR
A[Frontend] --> B(API Gateway)
B --> C[User Service]
C --> D[(Database)]
D --> E[Cache]
AI mengenali kurung tutup dan kurung siku yang hilang, lalu memperbaikinya secara instan.
Bahasa Alami ke Diagram
Mungkin fitur paling kuat adalah menghasilkan diagram dari deskripsi bahasa alami. Dengan alat seperti OpenDocs (platform dokumentasi VP), Anda cukup mendeskripsikan yang Anda inginkan:
“Buat diagram alur yang menunjukkan pengguna masuk. Jika kredensial valid, alihkan ke dasbor. Jika tidak valid, tampilkan pesan kesalahan dan izinkan 3 percobaan. Setelah 3 kegagalan, kunci akun.”
Mermaid yang Dihasilkan AI:
flowchart TD
Start([User Attempts Login]) --> EnterCreds[Enter Email & Password]
EnterCreds --> Validate{Validate Credentials}
Validate -->|Valid| Dashboard[Redirect to Dashboard]
Validate -->|Invalid| CheckAttempts{Attempts < 3}
CheckAttempts -->|Yes| Increment[Increment Attempt Counter]
Increment --> ShowError[Show Error Message]
ShowError --> EnterCreds
CheckAttempts -->|No| LockAccount[Lock Account for 15 min]
LockAccount --> SendAlert[Send Security Alert Email]
SendAlert --> End([Process Ends])
Dashboard --> End
Terjemahan Antar Jenis Diagram
AI juga dapat menerjemahkan antar format diagram yang berbeda. Butuh diagram PlantUML dikonversi ke Mermaid? Alat AI dapat menanganinya:
Input PlantUML:
@startuml
actor User
participant "Frontend" as FE
participant "Backend" as BE
database "DB" as DB
User -> FE: Click Login
FE -> BE: POST /login
BE -> DB: SELECT user
DB --> BE: user data
BE --> FE: JWT token
FE --> User: Show Dashboard
@enduml
Mermaid yang Dikonversi AI:
sequenceDiagram
actor User
participant Frontend
participant Backend
participant Database
User->>Frontend: Click Login
Frontend->>Backend: POST /login
Backend->>Database: SELECT user
Database-->>Backend: user data
Backend-->>Frontend: JWT token
Frontend-->>User: Show Dashboard
Integrasi Chatbot Interaktif
Beberapa platform kini menawarkan antarmuka chatbot untuk pembuatan diagram. Anda dapat melakukan percakapan:
Pengguna: “Tambahkan layanan baru bernama ‘Layanan Inventaris’ ke diagram arsitektur saya.”
AI: “Saya akan menambahkan Layanan Inventaris yang terhubung ke Layanan Produk dan Layanan Pesanan yang sudah Anda miliki.”
Diagram diperbarui secara otomatis
Pengguna: “Sebenarnya, buat juga terhubung ke database baru bernama ‘InventoryDB’.”
AI: “Selesai. Layanan Inventaris sekarang terhubung ke Layanan Produk, Layanan Pesanan, dan InventoryDB yang baru.”
Mengintegrasikan Diagram sebagai Kode ke dalam Alur Kerja Anda
Langkah 1: Mulai dari yang Kecil
Jangan mencoba membuat diagram seluruh sistem Anda sekaligus. Mulailah dengan satu komponen—mungkin alur autentikasi Anda atau fitur baru yang sedang Anda bangun.
Langkah 2: Sematkan dalam Dokumentasi
Simpan file Anda .mermaid berdampingan dengan dokumentasi Anda (misalnya, di dalam folder /docs ). Gunakan alat seperti mermaid-cli untuk merendernya selama proses pembangunan.
Langkah 3: Manfaatkan Mesin Terpadu VPasCode
Jika Anda bekerja dalam tim dengan preferensi yang beragam, VPasCode sangat berharga. Alat ini mendukung beberapa bahasa diagram sebagai kode dalam satu tempat:
# Di VPasCode, Anda dapat mencampur dan mencocokkan:
diagrams/
├── architecture.mermaid
├── deployment.puml # PlantUML
├── database-erd.mermaid
└── workflow.d2 # Bahasa D2
Langkah 4: Otomatisasi dengan CI/CD
Tambahkan langkah ke GitHub Actions atau GitLab CI Anda:
- name: Render Diagram Mermaid
run: |
for file in $(find docs -name "*.mermaid"); do
npx @mermaid-js/mermaid-cli -i $file -o ${file%.mermaid}.png
done
- name: Unggah ke Situs Dokumentasi
run: |
aws s3 sync docs/ s3://your-docs-bucket/
Langkah 5: Tinjau dalam Pull Requests
Jadikan kebijakan bahwa semua perubahan arsitektur memerlukan pembaruan diagram. Gunakan komentar PR untuk mendiskusikan perubahan visual:
Pemeriksa: “Bukankah cache seharusnya berada di antara Order Service dan Database? Saat ini hanya terpasang pada User Service.”
Penulis: “Tangkap yang bagus. Saya akan memperbarui diagram.”
Dampak Dunia Nyata: Sebuah Studi Kasus
Pertimbangkan sebuah startup fintech yang mengadopsi Diagram as Code dengan Mermaid dan VPasCode:
-
Sebelumnya: 47 file Visio statis, sebagian besar lebih dari 6 bulan usianya. Karyawan baru menghabiskan 3 minggu untuk memahami arsitektur.
-
Setelahnya: 12 diagram Mermaid, semua disimpan di Git, diperbarui dengan setiap fitur. Karyawan baru sudah produktif pada minggu pertama.
CTO tim mencatat: “Kami beralih dari diagram yang hanya menjadi kotak centang kepatuhan menjadi bagian hidup dari proses pengembangan kami. Saat kami mendebatkan arsitektur baru, kami membuka editor Mermaid dan benar-benar membuat sketsanya dalam kode. Ini adalah perubahan permainan.”
Masa Depan: Dokumentasi Berkelanjutan
Tujuan akhirnya adalah “dokumentasi berkelanjutan,” di mana diagram dihasilkan secara otomatis dari infrastruktur atau kode Anda. Alat-alat sudah mulai muncul yang dapat:
-
Pindai manifest Kubernetes Anda dan hasilkan diagram topologi layanan
-
Parse file OpenAPI/Swagger dan buat diagram alur API
-
Pantau sumber daya cloud Anda dan perbarui diagram arsitektur secara otomatis
Mermaid berada di pusat gerakan ini, menyediakan format berbasis teks yang sederhana yang dapat dihasilkan oleh mesin dan dipahami oleh manusia.
Mulai Hari Ini
Siap untuk melampaui gambar statis? Berikut rencana tindakan Anda:
-
Pasang ekstensi Mermaid di IDE favorit Anda (VS Code, IntelliJ)
-
Buat diagram pertama Anda dalam sebuah
.mdfile menggunakan sintaks Mermaid -
Jelajahi tingkat gratis VPasCode untuk mengalami pembuatan diagram berbasis AI
-
Mulai repositori dokumentasi yang hidup di samping basis kode Anda
-
Bagikan artikel ini dengan tim Anda dan mulailah percakapan
Arsitektur Anda layak lebih dari sekadar diagram berdebu di folder yang terlupakan. Sudah saatnya Anda memperlakukan diagram Anda sebagai aset kritis yang seharusnya.