claw-email/docs/architecture/overview.md

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:

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:

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 0002: Ingress uses a configurable external rules pipeline before dispatch
• ADR index

Tài liệu lịch sử

• Historical design input: docs/specs/2026-04-24-email-openclaw-bridge-design.md