speckle-server/docs/audit_report.md

# Cố Vấn Tái Cấu Trúc Bậc Cáo (Speckle Architecture Audit Report)

Tài liệu này là kết quả Audit kỹ thuật của hệ thống Speckle, do các AI Agent phân tích và chắt lọc dựa trên mã nguồn. Nó phục vụ cho bất cứ Dev Team nào muốn thiết kế lại, clone dự án, hoặc porting (chuyển ngôn ngữ) hoàn toàn cho một startup BIM mới.

## 1. Ưu điểm nổi bật (Strengths) đoạt giải kiến trúc
- **Khái niệm Data Hashing Graph**: Việc biến mô hình 3D (vertices, faces) thành các Node JSON có SHA256 ID là cốt lõi lớn nhất. Nếu 1 bức tường 3 triệu mặt cắt giống hệt nhau ở cả 2 commit, hash id của bức tường sẽ ko đổi, backend không lưu gấp đôi -> **Data deduplication thần thánh**.
- **Viewer quá mạnh mẽ**: Kỹ thuật Instanced Mesh (Batching) của `@speckle/viewer` đủ sức nhúng tòa nhà siêu to khổng lồ (> 1 triệu geometries) mượt mà lên WebGL. 
- **Decoupled Architecture**: Việc tách vụn Webhooks, Preview, IFC Conversion thành các Worker Jobs (Microservices) bảo vệ GraphQL Server luôn có phản hồi nhanh ở mức 20ms - 50ms.

## 2. Rủi ro / Điểm yếu hiện tại (Bottlenecks)
- **Node.js Memory Bound**: Mặc định Node giới hạn bộ nhớ V8 tầm 1.5GB - 4GB. Khi client đẩy lên 1 commit khổng lồ dính đến hàng trăm nghìn objects, tốc độ nhét object vào PostgreSQL nếu không có Batching rất dễ ngốn RAM + Thắt cổ chai. Việc team Speckle phải viết riêng luồng busboy-stream API để upload cho thấy Node.js backend đang phải gồng mình.
- **Dính chặt vào Apollo & CodeGen**: Frontend xài GraphQL bị khóa chặt với cấu trúc dữ liệu Backend. Việc đổi database từ Postgres sang MongoDB không sao (nếu backend vẫn giữ GQL schema), nhưng đổi Backend bỏ GraphQL là đập luôn toàn bộ Frontend.

## 3. Bản Kế Hoạch Tái Cấu Trúc (How to Re-write/Port this Project)
Giả định bạn muốn viết lại Speckle bằng `Golang + ReactJS + Postgres`.

### A. Core Backend API
- **Ngôn ngữ**: Rất khuyến khích dùng Go (Golang) hoặc Rust thay cho Node.js hiện tại để tăng thông lượng network throughput và memory safety gấp 10 lần.
- **Tiêu chuẩn Hash**: Bắt buộc phải sao chép chính xác hàm Hash SHA256 các node property của Speckle API (Cần đảo ngược/dịch mã code C# Speckle SDK) để tương thích ngược với các Plugin Revit/Rhino đã cài ở máy người dùng.
- **Database**: Vẫn phải là PostgreSQL (Hoặc CockroachDB). Dữ liệu là đồ thị (Graph), nhưng Speckle không dùng Neo4j mà dùng Postgres relation - Bạn phải giữ đúng kiến trúc bảng `objects`, `commits`, `branches`, và `streams`.

### B. Frontend
- Dẹp bỏ Nuxt 3 (Nếu team không thạo Vue). Xài Next.js 14+ (App Router).
- Phần `@speckle/viewer` tuyệt đối không nên viết lại (vì đó là công sức tối ưu toán học 5 năm trời). Gói nó thành một React Component `<Viewer>` qua `useRef` gắp thả cái canvas của Three.js thẳng vào DOM Node.
- Đọc stream API giải nén dữ liệu `@speckle/objectloader` giữ nguyên vì là pure TypeScript.

### C. Giao tiếp Thời gian thực (Realtime)
- Bỏ GraphQL Subscriptions nếu thấy nặng. Chuyển qua xài Server-Sent Events (SSE) hoặc WebSocket (Gorilla Mux / Socket.io) kết nối cùng Redis Pub/Sub. Cơ chế cực kỳ đơn giản: *"Có commit mới vào Stream X" -> Emit JSON -> Client tải lại.*