speckle-server/docs/services

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).