Belajar Software Architect - Architecture Documentation (C4, ADR)

#Pendahuluan

Setelah di episode 5 kalian mampu menyusun quality scenario terukur dan memilih tactics beserta trade-off-nya, muncul masalah baru: semua pemikiran itu hidup di kepala kalian. Pada episode ini kita bahas dokumentasi arsitektur — cara mengomunikasikan struktur dan keputusan agar tetap hidup setelah rapat selesai.

Dokumentasi arsitektur sering gagal di dua kutub ekstrem: dokumen Word ratusan halaman yang tidak pernah dibaca, atau tidak ada sama sekali ("kodenya saja adalah dokumentasi"). Keduanya salah. Yang dibutuhkan hanyalah dua artefak ringan: diagram yang bisa dipahami dalam satu menit (C4) dan catatan keputusan yang bisa diaudit bertahun-tahun (ADR).

#Masalah Diagram Arsitektur Tradisional

Diagram kotak-panah biasa gagal karena tiga alasan:

1. Tidak jelas level abstrasinya — satu gambar mencampur user, load balancer, class Java, dan database.
2. Tidak ada legenda audiens — gambar untuk CEO dan untuk engineer baru tampak sama.
3. Segera basi — diperbarui manual sekali lalu dilupakan; sistem berubah, diagram menyesatkan lebih parah daripada tanpa diagram.

Simon Brown menawarkan solusi elegan lewat C4 model: pikirkan seperti zoom Google Maps.

#Model C4: Empat Level Zoom

#Level 1: System Context

Satu diagram, seluruh cerita: sistem kalian di tengah, pengguna di kiri, sistem eksternal di kanan. Tidak ada detail internal. Audiensnya: siapa pun termasuk non-teknis. Ini diagram paling penting dan paling jarang dibuat.

[Customer] ──→ [Toko Online] ←── [Tim Ops/CS]
                  │
        ┌─────────┼────────────┐
        ▼         ▼            ▼
 [Payment Gateway][Email Provider][Logistics API]

#Level 2: Container

Masih bahasa teknologi tinggi tingkat aplikasi, bukan deployment: web app, mobile app, API server, database, cache, message broker. Panah menyatakan protokol komunikasi (HTTPS, TCP, AMQP). Audiens: engineer baru hari pertama — setelah membaca ini ia tahu bentuk besar sistem.

#Level 3: Component

Zoom ke dalam satu container: modul-modul di dalam API server (catalog, ordering, payment), komponen internalnya, dan dependensinya. Audiens: developer yang akan mengubah kode di container itu.

#Level 4: Code

Diagram class/UML. Jujur saja: ini cepat basi dan jarang bernilai — IDE modern sudah menghasilkannya on-demand. C4 tidak melarangnya, tetapi kebanyakan tim sebaiknya berhenti sampai level 3.

#Diagram as Code dengan Structurizr DSL

C4 paling bermanfaat ketika diagramnya diperlakukan seperti kode: versioned di git, direview lewat PR, dan bisa diregenerasi. Structurizr DSL adalah standar de facto:

workspace {
    model {
        customer = person "Customer"
        ops = person "Tim Ops"
 
        softwareSystem = softwareSystem "Toko Online" {
            web = container "Web App" {
                tags "frontend"
            }
            api = container "API Server" {
                tags "backend"
                uses inventoryDb "read/write"
            }
            inventoryDb = container "Database" {
                tags "database"
            }
            cache = container "Redis Cache"
        }
 
        payment = softwareSystem "Payment Gateway"
 
        customer -> softwareSystem.web "Beli produk"
        softwareSystem.web -> api "HTTPS"
        api -> payment "Charge via HTTPS"
        ops -> softwareSystem.api "Kelola order"
    }
 
    views {
        systemContext softwareSystem "context"
        container softwareSystem "containers"
    }
}

Manfaat nyata pendekatan as-code:

• Diff di PR — perubahan arsitektur terlihat baris demi baris, direview seperti kode.
• Konsistensi — satu definisi model, banyak view (context, container) dihasilkan ulang.
• Hidup lebih lama — karena upaya update rendah, kemungkinan diperbarui jauh lebih tinggi.

Strukturizr Lite yang kalian pasang di episode 0 merender file ini langsung di browser.

#Architecture Decision Records

Diagram menjawab "bagaimana bentuknya"; ADR menjawab pertanyaan yang lebih sulit: mengapa. Enam bulan lagi, orang baru (atau kalian sendiri yang sudah lupa) butuh tahu konteks keputusan — bukan cuma hasilnya.

Format paling populer (Michael Nygard) hanya lima bagian:

Prinsip-prinsip penting ADR:

• Immutable — ADR yang salah tidak diedit, melainkan superseded oleh ADR baru. Riwayat adalah nilai utamanya.
• One decision per record — ADR yang mencampur lima keputusan tidak bisa di-superseded sebagian.
• Simpan di repo — folder docs/adr/, nomor urut 0001-, 0002-, dst.
• Ringkas — satu-dua halaman maksimal. Kalau lebih panjang, kemungkinan kalian mencampur beberapa keputusan.

#Praktik: Menulis ADR Pertama Studi Kasus

Keputusan style dari episode 3 kini diformalkan. Inilah ADR lengkap pertama kita:

# 2. Gunakan Modular Monolith sebagai Starting Point
 
## Status
Accepted (2026-08)
 
## Konteks
Tim 6 developer membangun toko online dengan 500 ribu MAU
dan flash sale mingguan. Quality attributes prioritas:
availability checkout ≥99.95%, p99 read ≤300 ms,
consistency kuat di payment, deploy harian.
 
Opsi yang dievaluasi (episode 3):
- Microservices: scale & deploy independence, tetapi
  biaya operasional (platform, tracing, on-call) melebihi
  kapasitas tim saat ini; konsistensi payment menjadi sulit.
- Layered monolith: sederhana, tetapi boundary longgar
  berisiko big ball of mud dan scalability seluruh unit.
- Event-driven penuh: overkill untuk beban CRUD-dominan.
 
## Keputusan
Membangun modular monolith: satu unit deploy, lima modul
(catalog, ordering, payment, inventory, shipping) dengan
boundary bounded-context, interface publik eksplisit, dan
larangan akses tabel lintas modul. Komunikasi antar modul
untuk aliran non-kritis menggunakan in-process event bus
agar jalur migrasi ke services terbuka.
 
## Konsekuensi
+ Deployment & debugging sederhana; transaksi ACID lokal
+ Boundary modul = jalur ekstraksi service bertahap nanti
- Disiplin boundary harus dipaksakan tooling (fitness check)
- Scale selektif terbatas; flash sale ditangani caching &
  autoscaling horizontal keseluruhan aplikasi
Revisi jika: tim >15 developer, atau traffic >5x proyeksi.

Perhatikan bagian konsekuensi: ADR yang baik jujur pada harga yang dibayar, bukan promosi keputusan. Dan catatan pemicu revisi ("revisi jika...") membuat keputusan ini punya masa kedaluwarsa yang jelas.

#Menjaga Dokumentasi Tetap Hidup

Dua kebiasaan yang membuat dokumentasi tidak mati:

1. Definition of done mencakup diagram & ADR — PR yang mengubah struktur wajib menyertakan diff workspace.dsl atau ADR baru. Bukan pekerjaan sampingan, tapi bagian rilis.
2. Dokumentasi di dekat kode — folder docs/ dalam repo yang sama, dirender otomatis (misal via docs-as-code pipeline). Diagram yang tinggal di Google Drawings adalah diagram mati.

Anti-pattern yang harus dihindari: dokumen "arsitektur master" tunggal berisi segalanya. Ia akan basi pada sprint kedua. Pecah menjadi artefak kecil yang masing-masing punya pemilik dan pemicu pembaruan.

#Kesalahan Umum

• Diagram tanpa legenda & audiens — kotak tanpa makna teknologi dan panah tanpa protokol hanya dekorasi.
• ADR sebagai proposal marketing — yang menulis hanya memuat kelebihan; konsekuensi negatif disembunyikan. Pembaca dewasa akan curiga dan benar begitu.
• Mengedit ADR lama — riwayat rusak; supersede, jangan edit.
• C4 level 4 yang dirawat manual — buang tenaga; andalkan IDE.
• Dokumentasi setelah proyek selesai — pada titik itu konteks keputusan sudah hilang; tulis saat memutuskan.

#Penutup

Inti yang harus dibawa pulang:

• Dokumentasi arsitektur minimal efektif = C4 diagram + ADR, keduanya ringkas dan hidup di repo.
• C4 memberi empat level zoom; fokuslah pada context dan container — satu diagram, satu audiens, satu pertanyaan.
• Structurizr DSL membuat diagram jadi kode: versioned, direview di PR, regenerable.
• ADR mencatat mengapa: immutable, satu keputusan per record, jujur pada konsekuensi, punya pemicu revisi.
• Kalian kini punya ADR-0002 (modular monolith) sebagai artefak resmi pertama studi kasus.

Di episode 7 selanjutnya kita turun ke modularity & boundaries — cohesion vs coupling, cara mendesain module interface, dan bagaimana memaksa boundary modular monolith kita agar tidak tergerus seiring waktu. Sampai jumpa!