# SAD — Solution Architecture Document — <PROJECT>

| | |
|---|---|
| **Version** | 1.0 |
| **Date** | YYYY-MM-DD |
| **Author** | <SA> (skill sa-2-architecture) |
| **Status** | 🟡 Draft |
| **Approved by** | Tech Lead: — · Security: — · SRE: — |
| **Source** | CTX_… v1.0 · OPT_… v1.0 · QAS_… v1.0 |
| **Scope** | |
| **Confidence** | 🟡 |

## Change Log

| Version | Date | Người sửa | Thay đổi | ADR |
|---|---|---|---|---|
| 1.0 | | | Bản đầu | — |

> **Thẩm quyền khi mâu thuẫn:** sơ đồ thắng về **quan hệ và luồng** (ai gọi ai, thứ tự nào);
> bảng/văn bản thắng về **ràng buộc và con số** (timeout, quyền, định dạng, giới hạn).
> Mâu thuẫn ngoài hai loại trên là lỗi tài liệu, phải sửa chứ không phải chọn bên.

---

## 1. Tóm tắt cho người quyết định

*Năm câu. Đọc xong biết hệ thống gồm mấy khối, khối nào rủi ro nhất, quyết định lớn nhất là gì.*

| | |
|---|---|
| **Kiểu kiến trúc** | *(modular monolith / service theo bounded context / event-driven / hybrid)* |
| **Quyết định lớn nhất** | `ADR-nnn` — |
| **Rủi ro kiến trúc lớn nhất** | `ARISK-nn` — |
| **Cái này KHÔNG làm được** | *(giới hạn đã biết trước, ghi ra để không ai kỳ vọng sai)* |

## 2. Kiểu kiến trúc và lý do

Quyết định ở `ADR-001`. Tóm tắt lý do gắn với `ASR` và `CON`:

| Tín hiệu trong dự án này | Nghiêng về | Kết luận |
|---|---|---|
| `CON-04`: … team, ai release độc lập với ai | | |
| `ASR-…`: tải lệch giữa các phần | | |
| `CON-04`: năng lực đội vận hành | | |

🔴 **Modular monolith là mặc định hợp lý** cho ≤ 2 team và ranh giới nghiệp vụ chưa ổn định.
Tách service là quyết định phải *thắng* một lập luận, không phải điểm khởi đầu.

---

## 3. C4 — Mức 1: System Context

*Ai dùng hệ thống, hệ thống nói chuyện với cái gì bên ngoài. Không có chi tiết bên trong.*

<!-- archify: architecture · diagrams/SAD_c4-context.architecture.json -->
```mermaid
flowchart LR
```

**Legend:** ▭ hệ thống của ta · ▱ hệ thống ngoài · ○ người dùng ·
──▶ đồng bộ (ghi giao thức trên mũi tên) · ┄▶ bất đồng bộ

| Thực thể ngoài | Vai trò | Ai sở hữu | Giao thức | SLA của họ | `IF-nnn` |
|---|---|---|---|---|---|

---

## 4. C4 — Mức 2: Container

*Các khối chạy được và triển khai được (ứng dụng, CSDL, hàng đợi, job). Đây là sơ đồ dev dùng
nhiều nhất.*

<!-- archify: architecture · diagrams/SAD_c4-container.architecture.json -->
```mermaid
flowchart TB
```

**Legend:** *(bắt buộc — mũi tên không nhãn giao thức và không phân biệt sync/async là mũi tên
trang trí)*

### 4.1 Bảng container/component — `CMP-nn`

| ID | Tên | Trách nhiệm *(một câu)* | **Cái nó KHÔNG làm** | Dữ liệu sở hữu | Interface vào | Interface ra | Team | `ASR` ép ra |
|---|---|---|---|---|---|---|---|---|
| `CMP-01` | | | | | `IF-001` | `IF-004` | | `ASR-001` |

🔴 **Cột "cái nó KHÔNG làm" là cột ngăn phình chức năng.** Component không có ranh giới viết
ra sẽ nuốt dần mọi thứ trong 6 tháng.

🔴 Component không phục vụ `ASR` nào và không có nhu cầu chức năng rõ ⇒ hỏi lại vì sao nó tồn tại.

### 4.2 Ranh giới thay đổi

*Thay đổi loại nào chỉ chạm một container? Loại nào chạm nhiều? Đây là thước đo chất lượng
của cách phân rã.*

| Loại thay đổi hay xảy ra | Chạm những container nào | Có chấp nhận được không |
|---|---|---|
| Thêm một loại báo cáo | | |
| Thêm một kênh thanh toán | | |
| Đổi quy tắc tính phí | | |

Một loại thay đổi thường xuyên mà chạm ≥ 3 container ⇒ phân rã đang cắt sai chỗ.

---

## 5. C4 — Mức 3: Component *(chỉ cho container phức tạp nhất)*

*Không vẽ mức này cho mọi container. Vẽ cho cái khó nhất, để dev có mẫu.*

<!-- archify: architecture · diagrams/SAD_c4-component.architecture.json -->
```mermaid
flowchart TB
```

---

## 6. Luồng chính

*Sequence diagram cho 2–4 luồng quan trọng nhất. Mỗi luồng ghi rõ: đồng bộ hay bất đồng bộ,
timeout ở đâu, giao dịch bắt đầu và kết thúc ở đâu.*

### 6.1 <tên luồng>

<!-- archify: sequence · diagrams/SAD_luong-chinh.sequence.json -->
```mermaid
sequenceDiagram
```

| Bước | Thành phần | Đồng bộ? | Timeout | Lỗi thì sao | `FAIL` |
|---|---|---|---|---|---|

---

## 7. Deployment view

*Cái gì chạy ở đâu, mấy bản, ranh giới mạng, ranh giới tin cậy.*

<!-- archify: architecture · diagrams/SAD_deployment.architecture.json -->
```mermaid
flowchart TB
```

| Thành phần | Môi trường | Số bản | Cấu hình | Vùng/AZ | Ranh giới tin cậy |
|---|---|---|---|---|---|

**Ranh giới tin cậy** — nơi dữ liệu đi từ vùng ít tin cậy sang vùng tin cậy hơn. Mỗi ranh giới
phải có kiểm tra đầu vào; liệt kê ở `SEC`.

---

## 8. Quyết định kiến trúc đã ghi

| `ADR` | Quyết định | Trạng thái | Điểm radar | Có POC |
|---|---|---|---|---|
| `ADR-001` | Kiểu kiến trúc | Accepted | 9 | POC-01 ✅ |

*Sổ đầy đủ: `../00-index/ADL_<PROJECT>.md`*

## 9. Mối quan tâm xuyên suốt

*Những thứ mọi component đều phải làm giống nhau — không thống nhất ở đây thì mỗi dev một kiểu.*

| Mối quan tâm | Quyết định | Ở đâu | `ADR` |
|---|---|---|---|
| Định dạng log & correlation id | | `AGD` | |
| Xử lý lỗi & mã lỗi | | `ICD` | |
| Xác thực & phân quyền | | `SEC` | |
| Cấu hình & secret | | `SEC`, `INF` | |
| Múi giờ & định dạng thời gian | | `ICD` | |
| Số lớn (id/tiền) | | `ICD` | |
| Đa ngôn ngữ | | | |
| Idempotency | | `ICD`, `FAIL` | |

## 10. Giả định & Ngoài phạm vi

**Giả định:**

| ID | Giả định | Cách xác minh | Nếu sai |
|---|---|---|---|

**Ngoài phạm vi** *(quy tắc `D11` — những thứ người đọc có thể tưởng là có)*:

- *(ví dụ: không hỗ trợ đa vùng; DR dựa trên khôi phục từ backup, RTO 4 giờ)*
- *(ví dụ: không nhắm tới tải × 100 — ngưỡng xét lại: … giao dịch/giờ)*

## 11. Open Questions

| ID | Câu hỏi | Hỏi ai | Từ ngày | Chặn gì | Hệ quả nếu trả lời ngược |
|---|---|---|---|---|---|