Diagram C4 adalah metode visualisasi arsitektur yang distandarisasi yang dirancang untuk memodelkan sistem perangkat lunak pada berbagai tingkat abstraksi struktural. Dibangun secara native ke dalam Mermaid.js, c4mesin mengikuti empat tingkatan inti dari model C4: Konteks (ekosistem makro), Kontainer (aplikasi, layanan, dan basis data), Komponen (modul struktural internal), dan Interaksi dinamis. Alat ini menghilangkan kesulitan dalam styling CSS khusus dengan menerapkan blok arsitektur yang konsisten dan siap presentasi berdasarkan deklarasi teks Anda.
Memahami Abstraksi dan Kata Kunci Diagram C4
Mermaid mendukung empat header inisialisasi diagram khusus tergantung pada tingkat detail tata letak sistem Anda yang dibutuhkan:
C4Context: Berfokus pada tampilan gambaran besar, menampilkan pengguna, ekosistem perangkat lunak inti, dan ketergantungan eksternal tingkat tinggi.C4Container: Memperbesar satu tingkatan untuk menguraikan aplikasi mandiri, antarmuka frontend, mikroservis, sistem penyimpanan basis data, dan antrian.C4Component: Menggali lebih dalam ke dalam sebuah kontainer untuk menampilkan modul tingkat kode internal, seperti Kontroler, Layanan, dan Repositori.C4Dynamic: Berfokus pada pelacakan interaksi data saat runtime atau urutan transaksi langkah demi langkah antar blok infrastruktur.
Struktur Sintaks Dasar
Setiap diagram C4 dimulai dengan header tingkatan khusus, diikuti oleh pernyataan judul opsional dan komponen makro yang dipisahkan koma. Kurung menyimpan parameter, dengan string dibatasi oleh tanda kutip ganda.
C4Context
judul "Rancangan Konteks Sistem untuk Inti Internet"
Orang(customer, "Pelanggan Perbankan", "Seorang pelanggan bank dengan rekening pribadi.")
Sistem(banking_system, "Sistem Perbankan Internet", "Memungkinkan pelanggan melihat informasi rekening.")
Rel(customer, banking_system, "Menggunakan", "HTTPS")
Klasifikasi Makro Elemen C4 Lengkap
Perpustakaan C4 Mermaid menyediakan berbagai macam makro khusus yang luas untuk membedakan secara jelas antara komponen internal, sistem eksternal, dan lapisan basis data di semua tingkatan abstraksi.
1. Makro Orang & Pengguna
Person(alias, label, [deskripsi], [sprite], [tag]): Memodelkan pengguna manusia internal atau pemangku kepentingan.Person_Ext(alias, label, [deskripsi], [sprite], [tag]): Memodelkan pengguna eksternal (misalnya, pihak ketiga pemasok atau auditor) di luar batas organisasi inti Anda.
2. Makro Sistem & Ekosistem Perangkat Lunak
System(alias, label, [deskripsi], [sprite], [tag]): Mewakili kumpulan sistem perangkat lunak internal yang berada dalam cakupan langsung manajemen Anda.System_Ext(alias, label, [deskripsi], [sprite], [tag]): Memodelkan sistem perangkat lunak eksternal yang penting yang dikelola oleh pihak ketiga (misalnya, penyedia identitas, buku besar perbankan inti).SystemDb(alias, label, [deskripsi], [sprite], [tag]): Menampilkan kotak penyimpanan data tingkat sistem berbentuk silinder.SystemDb_Ext(alias, label, [deskripsi], [sprite], [tag]): Menampilkan lapisan basis data pihak ketiga eksternal.
3. Makro Lapisan Container (Lapisan C4Container)
Container(alias, label, teknologi, [deskripsi], [sprite], [tag]): Memodelkan aplikasi yang dapat dijalankan secara terpisah, server API, atau antarmuka frontend.ContainerDb(alias, label, teknologi, [deskripsi], [sprite], [tag]): Menampilkan pembungkus mesin basis data relasional atau non-relasional tingkat container.Container_Ext(alias, label, teknologi, [deskripsi], [sprite], [tag]): Mewakili layanan kontainer awan eksternal atau aplikasi.ContainerDb_Ext(alias, label, teknologi, [deskripsi], [sprite], [tag]): Mewakili lapisan penyimpanan basis data awan yang dikelola secara eksternal.
4. Makro Lapisan Komponen (Lapisan C4Component)
Komponen(alias, label, teknologi, [deskripsi], [sprite], [tag]): Memetakan modul tingkat kode internal, lapisan, atau pengontrol kelas.KomponenDb(alias, label, teknologi, [deskripsi], [sprite], [tag]): Memodelkan sistem penyimpanan mikro-komponen internal atau sistem penyimpanan sementara file tingkat rendah.
Kotak Batas & Pembungkusan Struktural
Untuk menunjukkan perimeter keamanan, firewall perusahaan, atau batas aplikasi logis, Mermaid menyediakan tiga pembungkus kotak yang dikelilingi tanda kurung khusus. Elemen yang berada di dalamnya dikelompokkan secara visual bersama.
Enterprise_Boundary(alias, label) { ... }: Membungkus sistem tingkat tinggi di dalam batas visual yang luas yang mewakili perimeter infrastruktur perusahaan atau perusahaan secara keseluruhan.System_Boundary(alias, label) { ... }: Mengelompokkan wadah aplikasi atau mikroservis yang saling terkait erat di dalam kotak ekosistem perangkat lunak yang terpadu.Container_Boundary(alias, label) { ... }: Mengisolasi komponen tingkat kode di dalam lapisan konteks modul aplikasi tunggal.
Operator Arah Hubungan Lanjutan
Menghubungkan blok dalam diagram C4 bergantung pada Relmakro atau variasi arahnya yang secara eksplisit didefinisikan. Alih-alih melewatkan garis bagan alir mentah, Anda melacak koneksi secara semantik dengan menyatakan vektor teknologi langsung di dalam blok logika.
| Token Sintaks Hubungan | Arah Panah Visual | Konteks Penyesuaian Penggunaan |
|---|---|---|
Rel(from, to, label, [tech]) |
Dinamis / Otomatis | Hubungan bawaan. Biarkan algoritma tata letak menentukan jalur garis terbaik. |
BiRel(from, to, label, [tech]) |
Dua Arah (<–>) | Menunjukkan saling tukar sapa dua arah, protokol duplex, atau proses sinkronisasi. |
Rel_Back(from, to, label, [tech]) |
Panah Terbalik Atas (<–) | Menggambar hubungan maju dalam logika kode tetapi membalik panah visual yang terlihat ke belakang. |
Rel_Neighbor(from, to, label, [tech]) |
Preferensi Tata Letak Horizontal | Memaksa simpul tujuan tetap tepat di samping simpul sumber pada baris horizontal yang sama. |
Rel_Down(from, to, label, [tech]) / Rel_D(...) |
Lurus ke Bawah (v) | Memaksa aliran data vertikal turun ke lapisan basis data atau proses latar belakang berikutnya. |
Rel_Up(from, to, label, [tech]) / Rel_U(...) |
Langsung Ke Atas (^) | Memaksa jalur hubungan bergerak lurus ke atas menuju komponen antarmuka pengguna klien. |
Rel_Kiri(from, to, label, [tech]) / Rel_L(...) |
Langsung Ke Kiri (<-) | Mengarahkan jalur secara horizontal ke sisi kiri elemen kanvas. |
Rel_Kanan(from, to, label, [tech]) / Rel_R(...) |
Langsung Ke Kanan (->) | Mengarahkan jalur secara horizontal ke sisi kanan elemen kanvas. |
Pengaturan Gaya Dinamis Kustom & Penandaan (Overshoot Bentuk C4)
Untuk menandai aplikasi lama, menonjolkan sistem premium, atau menyoroti aliran data aman, Anda dapat membuat gaya kustom dengan menggunakan mesin penanda elemen. Anda menentukan matriks properti penanda di bagian atas dokumen Anda, lalu menambahkan label penanda tersebut ke definisi elemen Anda.
Kata Kunci Modifikasi Gaya:
UpdateGayaElemen(namaElemen, warnaLatar, warnaFont, [warnaBatas], [bayangan]): Penggantian langsung palet latar belakang default kotak elemen yang eksplisit.UpdateGayaRel(from, to, warnaGaris, warnaTeks): Secara eksplisit menargetkan rute koneksi untuk mengubah warna jalur garis atau deskripsi koneksi.
C4Context
judul "Peta Arsitektur Global Berkode Warna Kustom"
Sistem(legacy_api, "Inti Penagihan Lama", "Memproses pembaruan langganan.")
Sistem(modern_portal, "Portal Dashboard Pelanggan", "Mesin tampilan web pengguna modern.")
%% Kustomisasi warna langsung
UpdateGayaElemen(legacy_api, "#d9534f", "#ffffff", "#c9302c")
UpdateGayaElemen(modern_portal, "#5cb85c", "#ffffff", "#4cae4c")
Blue Print Dunia Nyata: Peta Wadah Batas Sistem E-Commerce Perusahaan
Blue print wadah yang komprehensif dan berlapis ini melacak ekosistem e-commerce daring. Ia mengisolasi server inti internal menggunakan Batasan_Sistem wadah blok, menerapkan relay pemberitahuan awan eksternal melalui System_Ext, memetakan penyimpanan basis data relasional internal bersama layanan mikro pelacakan eksternal, dan menetapkan saluran komunikasi menggunakan parameter tumpukan teknologi yang eksplisit.
C4Container
judul "Rancangan Kerangka Kontainer untuk Platform E-Commerce Perusahaan"
Orang(customer, "Pembeli Online", "Menjelajahi item katalog dan menambahkan produk ke keranjang digital mereka.")
System_Ext(payment_gateway, "Layanan API Stripe", "Kotak penyimpanan kartu kredit pihak ketiga dan mesin pemroses.")
System_Boundary(ecommerce_scope, "Perimeter Inti E-Commerce") {
Container(frontend_app, "Aplikasi Web Toko", "Next.js, React", "Mengirimkan aset statis dan menangani sesi keranjang pengguna.")
Container(checkout_service, "Layanan Mikro Checkout", "Node.js, Express", "Memproses alur kerja keranjang belanja dan menghitung pajak.")
ContainerDb(order_db, "Database Buku Catatan Pesanan", "PostgreSQL", "Menyimpan baris transaksi historis dan catatan buku ledger yang aman.")
}
%% Jalur Interaksi Arsitektural
Rel(customer, frontend_app, "Melihat produk dan memesan menggunakan", "HTTPS/Browser")
Rel_Down(frontend_app, checkout_service, "Mengirimkan transaksi payload belanja melalui", "JSON/REST API")
Rel_Right(checkout_service, order_db, "Menyimpan status transaksional di dalam", "SQL/JDBC Koneksi")
Rel_Left(checkout_service, payment_gateway, "Mengotorisasi panggilan pembayaran yang telah ditempatkan token dengan", "API TLS/Aman/HTTPS")
Kesalahan Sintaks Umum & Kendala Sistem
Saat mengompilasi peta C4 yang bersih untuk kerangka perangkat lunak, waspadai parameter eksekusi berikut untuk mencegah kerusakan diagram:
- Format Pemisah Koma: Berbeda dengan hampir semua skema Mermaid lainnya, makro C4 mengharuskan koma yang ketat di antara parameter:
Orang(id, "Label", "Desc"). Melewatkan koma pemisah akan membuat pembuat tata letak benar-benar gagal. - Kutipan Label yang Direservasi: Bidang tampilan, tag teknologi, dan blok deskripsi di dalam makro *harus* dibungkus dengan tanda kutip ganda yang jelas. Menempatkan teks mentah ke dalam bidang tanpa bungkus kutipan akan menyebabkan kesalahan parsing yang merusak.
- Urutan Penempatan Batas: Saat membungkus elemen di dalam
System_BoundaryatauEnterprise_Boundaryblok, Anda harus secara eksplisit membersihkan isi ruang kerjanya menggunakan kurung kurawal standar{ }. Meninggalkan kurung batas terbuka atau mencocokkannya secara salah akan merusak tata letak rendering. - Instansiasi Alias Dinamis: Anda tidak dapat menggambar hubungan (
Rel) ke identifikasi alias yang belum secara eksplisit diinisialisasi oleh blok makro elemen di atasnya. Pertahankan alur deklarasi Anda berjalan secara progresif dari atas ke bawah.