docs: reorganize readme and architecture docs

2026-04-29 00:50:08 +07:00
parent fac874e747
commit a499841b1e
2 changed files with 130 additions and 53 deletions
@@ -0,0 +1,101 @@
+# Technical Overview
+
+## Mục đích
+
+Tài liệu này là technical overview hiện hành của `Email-OpenClaw Bridge`. `README.md` chỉ giữ phần onboarding và vận hành cơ bản; phần này giữ các chi tiết kỹ thuật bền vững hơn về flow, package layout, state machine và công nghệ chính.
+
+## Luồng xử lý
+
+Bridge xử lý email theo pipeline sau:
+
+```text
+Ingress (IMAP) → Safety Checks → External Rules → Dispatch (OpenClaw) → Callback → Egress (SMTP reply)
+```
+
+Các giai đoạn runtime chính:
+
+1. IMAP watcher theo dõi `INBOX` bằng IDLE và fetch email chưa đọc.
+2. Safety checks loại bỏ mail từ chính hệ thống và chặn duplicate theo `message_id`.
+3. External rules pipeline áp whitelist/blocklist và sinh `DispatchContext`.
+4. Thread resolution gắn `thread_id` dựa trên quan hệ email đã biết.
+5. Task được lưu vào SQLite với trạng thái pipeline hiện tại.
+6. OpenClaw nhận request xử lý và callback về bridge.
+7. Callback cập nhật `AIResponse`, sau đó bridge gửi phản hồi lại qua SMTP.
+
+## Package layout
+
+- `cmd/bridge`
+  - Entrypoint của process, wiring config, DB, IMAP watcher, HTTP router và SMTP egress.
+- `internal/config`
+  - Đọc `.env`, chuẩn hóa default như `LISTEN_ADDR`, `CALLBACK_BASE_URL`, và validate biến bắt buộc.
+- `internal/database`
+  - Khởi tạo SQLite qua GORM, định nghĩa `Task` model, repository helpers và health check DB.
+- `internal/mail`
+  - Chứa IMAP ingress, thread resolution, proxy support cho IMAP, retry logic và SMTP egress.
+- `internal/rules`
+  - External rules pipeline, whitelist/blocklist rules và rule metadata dùng cho dispatch.
+- `internal/ai_client`
+  - HTTP client gọi OpenClaw và gửi metadata/callback information ra ngoài.
+- `internal/api`
+  - HTTP router cho `healthz`, `readyz` và `POST /callback`.
+- `internal/logging`
+  - Helper tạo structured logger theo `task_uuid`, `thread_id`, `message_id`.
+
+## Task state machine
+
+Task được lưu trong SQLite và đi qua các trạng thái sau:
+
+```text
+RECEIVED → AI_PROCESSING → CALLBACK_DONE → COMPLETED
+    ↓           ↓                ↓
+ IGNORED      FAILED        SMTP_RETRYING → FAILED
+```
+
+- `IGNORED`
+  - Mail bị anti-loop, duplicate, hoặc bị external rules reject.
+- `RECEIVED`
+  - Task đã được lưu và sẵn sàng dispatch.
+- `AI_PROCESSING`
+  - Request đã được gửi sang OpenClaw.
+- `CALLBACK_DONE`
+  - Callback hợp lệ đã cập nhật `AIResponse`.
+- `SMTP_RETRYING`
+  - Đang retry gửi email phản hồi.
+- `COMPLETED`
+  - Toàn bộ pipeline kết thúc thành công.
+- `FAILED`
+  - Hết retry hoặc gặp lỗi không recoverable.
+
+## HTTP và health behavior
+
+- `GET /healthz`
+  - Trả `200 {"status":"ok"}` nếu process đang sống.
+- `GET /readyz`
+  - Trả `200` khi DB writable và `BRIDGE_CALLBACK_TOKEN` có mặt.
+  - Trả `503` nếu DB không writable hoặc config bắt buộc cho callback chưa sẵn sàng.
+- `POST /callback`
+  - Yêu cầu header `X-Bridge-Token`.
+  - Nhận payload callback từ OpenClaw, cập nhật task và kích hoạt SMTP egress bất đồng bộ.
+
+## Công nghệ chính
+
+- Go
+  - Runtime chính, phù hợp với service nhỏ gọn và dễ deploy.
+- SQLite + GORM
+  - Giữ state cục bộ đơn giản, không cần service DB riêng cho v1.
+- `github.com/emersion/go-imap/v2`
+  - Hỗ trợ IMAP IDLE và xử lý mailbox theo flow hiện tại.
+- `gin-gonic/gin`
+  - Cung cấp HTTP router tối giản cho health endpoints và callback.
+- `log/slog`
+  - Structured logging chuẩn thư viện chuẩn của Go.
+
+## ADR liên quan
+
+- [ADR 0001: IMAP thread resolution prefers In-Reply-To and falls back to References](../adr/0001-imap-thread-resolution.md)
+- [ADR 0002: Ingress uses a configurable external rules pipeline before dispatch](../adr/0002-external-rules-pipeline.md)
+- [ADR index](../adr/README.md)
+
+## Tài liệu lịch sử
+
+- Historical design input: [docs/specs/2026-04-24-email-openclaw-bridge-design.md](../specs/2026-04-24-email-openclaw-bridge-design.md)