Speckle Server - Business Logic & Architecture
Tài liệu nền tảng mới ASP.NET/Blazor
Bộ tài liệu dưới đây dùng cho hướng xây mới một nền tảng Speckle-compatible bằng Blazor WebAssembly, ASP.NET Core, PostgreSQL và C++ services:
- Business Requirements
- Technical Architecture
- Speckle Compatibility Contract
- Data Model
- API Spec
- Upload, Convert và Viewer Pipeline
- Blazor UI Module Spec
- MVP Implementation Plan
Đây là tài liệu tập trung vào Business Logic của toàn bộ giải pháp Speckle Server, dùng để tái thiết kế, chuyển đổi nền tảng hoặc để onboarding thành viên mới một cách nhanh nhất.
1. Quick Info
Speckle là một "Data Hub" mã nguồn mở dành cho ngành AEC (Architecture, Engineering, Construction). Speckle không lưu trữ file tĩnh mà băm nhỏ (decompose) các model 3D thành dữ liệu Object/JSON.
- Tech Stack hiện tại:
- Backend: Node.js (TypeScript), Express, Apollo GraphQL.
- Frontend: Vue 3, Nuxt 3 (SSR).
- Khác: Three.js (Viewer), Postgres (DB), Redis (Cache/PubSub), Minio/S3 (Blob storage).
2. Các thực thể cốt lõi (Core Entities)
Bạn cần hiểu các thuật ngữ sau vì chúng là xương sống của business:
| Thực thể | Mô tả |
|---|---|
| User | Người dùng hệ thống. Có Role (ServerAdmin, ServerUser). |
| Stream (Project) | Tương tự như một kho chứa (Repository) lưu trữ model. |
| Branch (Model) | Một nhánh của Stream, đại diện cho những phiên bản của một thiết kế hoặc một category (ví dụ: architectural, structural). |
| Commit (Version) | Một snapshot dữ liệu được đẩy lên Branch. Chứa metadata và tham chiếu tới một thẻ objectId gốc (root object). |
| Object | Đơn vị dữ liệu nhỏ nhất. Khi lấy dữ liệu 3D, Client/Plugin phân tách các mặt cắt, vật liệu... thành các Object nhỏ và gửi lên server. Có tính Immutable và được băm (hash) thành ID. Chứa các tham chiếu (references) tới các mảng Object khác. |
| Workspace | (Tính năng Enterprise) Không gian làm việc quản lý nhiều Project và Billing. |
3. Kiến trúc luồng hệ thống
- Desktop Client / Web App sử dụng REST API (hoặc SDK) kết nối với Server với token.
- Dữ liệu khi Push được gọi là Commit, dữ liệu payload được chia thành nhiều Objects và push đồng thời lên backend.
- Backend GraphQL xử lý Metadata, còn dữ liệu thô (Object payload) được gửi lên Server theo lô (batch) và nhét vào Blob storage (S3) hoặc lưu trực tiếp vào cơ sở dữ liệu
objects. - Redis đóng vai trò Pub/Sub để push event qua WebSockets/GraphQL Subscriptions tới các client đang online (Realtime Updates).
- Khi có bản lưu (Commit) mới, hệ thống Microservices chạy ngầm:
- Preview Service: Bắt event từ Redis, kéo object xuống, chuyển tải vào engine web-standard, chụp lại screenshot rồi lưu thành ảnh cho frontend.
- Webhook Service: Bắn thông tin tới các tool thứ 3 của người dùng.
- Automate: Trigger các function tự động hóa của user trên server.
4. Documentation Structure
Chi tiết luồng hoạt động từng hệ thống con được ghi trong các thư mục sau:
- Backend API & DB (Node.js)
- Frontend (Vue/Nuxt 3)
- Microservices (File import, Webhook, Preview)
- Core 3D Engine (Viewer)
5. Portability Note (Viết lại ngôn ngữ)
Tính tái định tuyến khả thi (High Portability):
- Logic backend tương đối stateless nhưng phụ thuộc nặng vào GraphQL Federation/Apollo và Postgres DB Schema.
- Có thể rewrite qua Go / C# / Rust nhưng phải đảm bảo:
- Kế thừa chuẩn xác thuật toán Hash Object của Speckle (để objectId luôn khớp).
- Maintain được cấu trúc Database Schema (hoặc tự chuyển đổi Data Mapper hiệu quả).
- Quản lý Pub/Sub cực tốt để giữ kết nối Realtime.
Xem thư mục con để rõ chi tiết logic từng module.