# Microservices Architecture (Speckle Automation/Workers)

Ngoài ứng dụng tải API chính (`packages/server`), Speckle tách các tiến trình chạy nặng phần CPU / IO ra thành nhiều Microservices chạy độc lập, giao tiếp với nhau bằng Redis hoặc Polling Database. Nếu một service sập, core API vẫn hoạt động bình thường.

## 1. Cơ chế giao tiếp cốt lõi
Hầu hết các services này không lắng nghe API HTTP request từ User. Thay vào đó, nó lắng nghe Events.
Ví dụ: Khi User tạo một Commit mới ở main server, main server bắn một event vào `Redis Pub/Sub` hoặc `Bull Queue`. Microservice "ứng trực" ở Queue đó sẽ chộp lấy và xử lý công việc mất nhiều thời gian.

## 2. Preview Service (Chụp ảnh 3D)
Nằm tại `packages/preview-service`.
- **Mục tiêu**: Tránh việc phải tải cục thiết kế 3D nặng 50MB chỉ để thấy cái thumbnail.
- **Tiến trình**:
  1. Lắng nghe event `commit_created`.
  2. Bật một trình duyệt Headless (Puppeteer) ngầm.
  3. Load `packages/viewer` trong tab ẩn.
  4. Stream dữ liệu object xuống viewer, cho camera tự động căn giữa (Focus/Zoom extent) toàn bộ toà nhà.
  5. Gọi hàm chụp lại canvas của ThreeJS (Screenshot to base64 buffer), sau đó bắn ảnh này lưu vào Database/S3 với nhãn là thumbnail của commit đó.

## 3. Webhook Service
Nằm tại `packages/webhook-service`.
- **Mục tiêu**: Khi có thay đổi mô hình, cần Notify sang Slack, Zalo, hoặc Trigger Pipeline hệ thống công ty XYZ.
- **Tại sao cần tách ra?**: Người dùng có thể cấu hình URL của webhook đến 1 server chậm/chết. Nếu để Server chính chờ timeout sẽ treo Thread Nodejs.
- **Tiến trình**: Service bắt event -> bốc HTTP Request (axios/fetch) đẩy dữ liệu -> Retry nếu lỗi (Exponential backoff) thông qua `bull` Queue. 

## 4. Fileimport / IFC Import Service
Nằm tại `packages/fileimport-service` & `packages/ifc-import-service`.
- **Mục tiêu**: Speckle sinh ra là để xử lý plugin Native (Revit, Rhino, AutoCad trực tiếp gửi lên thẳng bằng C# SDK). Tuy nhiên nếu dev/người dùng đẩy trực tiếp 1 file IFC thô hoặc OBJ/STL lên Web Upload, hệ thống cần convert.
- **Tiến trình**:
  1. User upload file tĩnh lên `/api/stream/..`
  2. Main server ném file vào MinIO/Blob sau đó lưu event "Bắt đầu convert".
  3. `ifc-import-service` đọc Blob về, phân tích file `IFC` (Dùng thư viện WebAssembly hoặc bin parser như `web-ifc`).
  4. Dịch các entity IFC ngược lại thành cây Speckle JSON Objects và sau đó push lại vào Main Server.

## 5. Portability Note (Viết Lại Các Service)
- Mảng micro-service này là thứ **Dễ đổi/rewrite nhất**.
- Bất cứ ngôn ngữ nào (Python, Go, Rust) kết nối được vào Postgres / Redis của Speckle là lập tức có thể Code ngay một worker ngầm (VD: Viết một service AI bằng Python tự động đọc hình học Speckle và gửi cảnh báo thiết kế sai). Kiến trúc Event-driven và DB share này hoàn toàn lỏng lẻo. Cực kỳ có lợi để team mở rộng logic ngoài lề (Automate).