Architecture Decision Records (ADR)

Apa itu ADR

• Dokumen singkat yang mencatat keputusan arsitektur penting beserta konteksnya
• Menjawab: "Kenapa kita memilih X, bukan Y?"
• Bukan dokumentasi teknis biasa — fokus pada keputusan dan alasan di baliknya
• Diperkenalkan oleh Michael Nygard, sekarang jadi praktik umum di industri

Mengapa ADR Penting

• Konteks keputusan sering hilang saat anggota tim berganti
• Tanpa ADR, engineer baru sering mempertanyakan atau mengubah keputusan lama tanpa mengerti konsekuensinya
• Menghindari rapat berulang untuk mendiskusikan hal yang pernah diputuskan
• Menjadi bukti bahwa keputusan dibuat dengan pertimbangan, bukan sembarangan

Struktur ADR

Title

Singkat, gunakan format: [nomor] - [judul keputusan] Contoh: 0012 - Gunakan PostgreSQL sebagai database utama

Status

• Proposed: sedang dalam diskusi
• Accepted: sudah diputuskan dan diimplementasi
• Deprecated: pernah berlaku tapi sudah digantikan
• Superseded by: digantikan oleh ADR lain

Context

• Latar belakang dan masalah yang mendorong keputusan ini
• Fakta-fakta relevan, constraint, dan pertimbangan teknis
• Tulis apa adanya tanpa bias terhadap keputusan akhir

Decision

• Keputusan yang diambil, ditulis secara tegas
• Contoh: "Kami akan menggunakan event-driven architecture untuk komunikasi antar service"

Consequences

• Dampak positif dan negatif dari keputusan ini
• Trade-off yang diterima
• Hal-hal yang harus diperhatikan ke depannya

Contoh ADR Sederhana

# 0007 - Gunakan Redis untuk session storage

## Status
Accepted

## Context
Aplikasi saat ini menyimpan session di database PostgreSQL.
Dengan meningkatnya traffic, query session menjadi bottleneck.
Tim membutuhkan solusi yang lebih cepat untuk read/write session.

## Decision
Kami akan menggunakan Redis sebagai session store.
PostgreSQL tetap digunakan untuk data permanen.

## Consequences
+ Latency session read/write turun dari ~20ms ke <1ms
+ Horizontal scaling menjadi lebih mudah
- Tim perlu memahami cara operasikan Redis
- Perlu strategi backup untuk data session penting
- Menambah satu komponen infrastruktur yang harus di-maintain

Di Mana Menyimpan ADR

• Dalam repository kode, di folder /docs/adr/ atau /adr/
• Disimpan bersama kode agar versi ADR selaras dengan versi kode
• Bisa juga di wiki (Notion, Confluence) tapi lebih sulit di-track perubahannya

Kapan Membuat ADR

• Setiap keputusan arsitektur yang signifikan dan tidak mudah di-reverse
• Pemilihan teknologi utama (database, framework, bahasa)
• Perubahan pola arsitektur (dari monolith ke microservices, dll)
• Keputusan trade-off yang mungkin akan dipertanyakan di masa depan
• Tidak perlu untuk keputusan kecil sehari-hari

Praktik Terbaik

• Tulis ADR saat keputusan baru dibuat, bukan setelah lama berlalu
• ADR bersifat immutable — jangan edit ADR lama, buat ADR baru yang men-supersede
• Libatkan tim dalam diskusi sebelum ADR di-accept
• Buat template standar agar semua ADR memiliki format yang konsisten
• Nomori ADR secara berurutan agar mudah di-referensikan