Architecture Decision Records (ADR)
Nhật ký các quyết định kỹ thuật quan trọng của dự án — trả lời "tại sao lại làm thế này" thay vì "làm cái gì" (cái gì đã có trong code/docs khác).
Quy tắc
- Mỗi ADR là 1 file, đánh số tuần tự
NNNN-slug-tieng-anh-khong-dau.md. - Dùng
template.mdkhi tạo ADR mới. - Không sửa lại ADR đã Accepted khi quyết định thay đổi — tạo ADR mới,
set
Supersedes/Superseded byđể link 2 chiều, đổi status ADR cũ thànhSuperseded. - Khi nào cần tạo ADR: xem quy tắc trong
CLAUDE.mdở root (mục "Architecture Decision Records"). - Cập nhật bảng dưới đây mỗi khi thêm/đổi status một ADR.
Danh sách ADR
| # | Tiêu đề | Status | Ngày |
|---|---|---|---|
| 0001 | Microservices với NestJS trong NX monorepo | Accepted | ~2026-06-27 |
| 0002 | Database-per-service, multi-Postgres container | Accepted | ~2026-06-27 |
| 0003 | GraphQL additive layer tại api-gateway | Accepted | 2026-07-24 |
| 0004 | OpenTelemetry + SigNoz cho observability | Accepted | ~2026-06-27 |
| 0005 | Keycloak cho identity/auth | Accepted | ~2026-06-27 |
| 0006 | Kafka + BullMQ song song cho messaging | Accepted | ~2026-06-27 |
| 0007 | Tách 2 tầng reverse proxy (NestJS vs Nginx) | Accepted | ~2026-06-27 |
Các ADR 0001–0007 được backfill ngày 2026-07-25: tái tạo lại từ source code,
docs/*.mdvà git log, không phải viết tại thời điểm ra quyết định gốc. Ngày đánh dấu~là ước tính (dựa trên commit sớm nhất chạm tới phần liên quan), không phải ngày quyết định thực tế được đưa ra. Từ ADR 0008 trở đi, viết ADR trước khi implement để ngày ghi nhận chính xác.