docs: reorganize readme and architecture docs

README.md

@@ -1,38 +1,26 @@
 # Email-OpenClaw Bridge
 
-Tự động xử lý email bằng OpenClaw AI theo luồng:
+Bridge tự động xử lý email bằng OpenClaw AI theo luồng:
 
-```
-Ingress (IMAP) → Safety Checks → External Rules → Apply Context → Dispatch (OpenClaw) → Callback → Egress (SMTP reply)
+```text
+Ingress (IMAP) → Safety Checks → External Rules → Dispatch (OpenClaw) → Callback → Egress (SMTP reply)
 ```
 
-## Tính năng
+README này tập trung vào onboarding và vận hành cơ bản. Chi tiết kỹ thuật hiện hành được tách sang `docs/architecture/overview.md`.
 
-- **IMAP IDLE** — theo dõi mailbox realtime, nhận email mới tức thì
-- **Threading** — giữ nguyên email thread qua `In-Reply-To` / `References`
-- **Idempotency** — chống duplicate theo `message_id`
-- **Anti-loop & Whitelist** — bỏ qua email từ chính hệ thống, chỉ xử lý sender được phép
-- **External Rules** — pipeline configurable: whitelist, blocklist, và rule metadata cho dispatch
-- **Retry** — tối đa 3 lần với backoff 1s → 5s → 15s cho cả OpenClaw và SMTP
-- **Stateful** — SQLite lưu trạng thái pipeline, không mất dữ liệu khi restart
+## Tính năng chính
 
-## Kiến trúc
+- Theo dõi mailbox realtime bằng IMAP IDLE
+- Giữ thread email qua `In-Reply-To` và `References`
+- Chống duplicate theo `message_id`
+- Chặn anti-loop và hỗ trợ whitelist/blocklist
+- Gửi callback vào bridge rồi phản hồi lại qua SMTP
+- Lưu trạng thái pipeline bằng SQLite để không mất tiến trình khi restart
 
-```
-cmd/bridge/main.go           Entrypoint
-internal/
-├── config/                   Đọc cấu hình từ .env
-├── database/                 SQLite + GORM, auto-migrate
-├── logging/                  Structured JSON logging (slog)
-├── api/                      HTTP server (Gin): health checks, webhook callback
-├── mail/                     IMAP ingress + SMTP egress
-└── ai_client/                OpenClaw HTTP dispatch
-```
-
-## Yêu cầu
+## Yêu cầu tối thiểu
 
 - Go 1.23+
-- Docker & Docker Compose (cho deploy)
+- Docker và Docker Compose nếu chạy bằng container
 
 ## Quickstart
 
@@ -43,7 +31,7 @@ cp .env.example .env
 # Sửa .env với thông tin IMAP/SMTP/OpenClaw thực tế
 ```
 
-### 2. Chạy local (development)
+### 2. Chạy local
 
 ```bash
 go run ./cmd/bridge
@@ -56,51 +44,39 @@ docker compose up -d
 docker logs -f claw-email-bridge
 ```
 
-## Cấu hình (.env)
+## Cấu hình `.env`
 
 | Biến | Bắt buộc | Mô tả |
 |---|:---:|---|
 | `IMAP_HOST` | ✅ | IMAP server hostname |
-| `IMAP_PORT` | ✅ | IMAP port (thường `993`) |
+| `IMAP_PORT` | ✅ | IMAP port, thường là `993` |
 | `IMAP_USER` | ✅ | IMAP username |
 | `IMAP_PASS` | ✅ | IMAP password |
 | `SMTP_HOST` | ✅ | SMTP server hostname |
-| `SMTP_PORT` | ✅ | SMTP port (thường `587`) |
+| `SMTP_PORT` | ✅ | SMTP port, thường là `587` |
 | `SMTP_USER` | ✅ | SMTP username |
 | `SMTP_PASS` | ✅ | SMTP password |
 | `OPENCLAW_URL` | ✅ | OpenClaw API endpoint |
-| `OPENCLAW_API_KEY` | | OpenClaw API key (nếu cần) |
+| `OPENCLAW_API_KEY` | | OpenClaw API key nếu cần |
 | `BRIDGE_CALLBACK_TOKEN` | ✅ | Token xác thực webhook callback |
-| `SYSTEM_EMAIL` | ✅ | Email của hệ thống (dùng cho anti-loop) |
+| `SYSTEM_EMAIL` | ✅ | Email của bridge, dùng cho anti-loop |
 | `WHITELIST_EMAILS` | | Danh sách email được phép, phân cách bằng dấu phẩy |
-| `IMAP_PROXY_URL` | | SOCKS5 proxy cho IMAP (vd: `socks5://user:pass@host:port`) |
-| `LISTEN_ADDR` | | Địa chỉ bind HTTP server cục bộ (mặc định `:8080`) |
-| `CALLBACK_BASE_URL` | | Base URL public để tạo `callback_url` gửi OpenClaw (mặc định theo `LISTEN_ADDR`, ví dụ `http://localhost:8080`) |
+| `BLOCKLIST_EMAILS` | | Danh sách email bị chặn, phân cách bằng dấu phẩy |
+| `IMAP_PROXY_URL` | | Proxy cho IMAP, hỗ trợ `socks5://`, `http://`, `https://` |
+| `LISTEN_ADDR` | | Địa chỉ bind HTTP server, mặc định `:8080` |
+| `CALLBACK_BASE_URL` | | Base URL public để tạo `callback_url`, mặc định suy ra từ `LISTEN_ADDR` |
 
-## Health Checks
+## Health checks
 
 | Endpoint | Mục đích |
 |---|---|
-| `GET /healthz` | Liveness — process còn sống |
-| `GET /readyz` | Readiness — DB writable + config hợp lệ |
+| `GET /healthz` | Liveness check, xác nhận process còn sống |
+| `GET /readyz` | Readiness check, xác nhận DB writable và config bắt buộc hợp lệ |
 
-## Pipeline trạng thái
+## Đọc thêm
 
-```
-RECEIVED → AI_PROCESSING → CALLBACK_DONE → COMPLETED
-    ↓           ↓                ↓
- IGNORED      FAILED        SMTP_RETRYING → FAILED
-```
-
-## Công nghệ
-
-| Thành phần | Thư viện |
-|---|---|
-| HTTP Server | [gin-gonic/gin](https://github.com/gin-gonic/gin) |
-| Database | [GORM](https://gorm.io) + [modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite) (pure Go, no CGO) |
-| IMAP | [emersion/go-imap](https://github.com/emersion/go-imap) |
-| Logging | [log/slog](https://pkg.go.dev/log/slog) (stdlib) |
-| Config | [joho/godotenv](https://github.com/joho/godotenv) |
+- [Technical overview](docs/architecture/overview.md)
+- [Architecture Decision Records](docs/adr/README.md)
 
 ## License