docs: add comprehensive business logic and architecture documentation

docs/README.md

@@ -0,0 +1,51 @@
+# Speckle Server - Business Logic & Architecture
+
+Đâ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
+1. **Desktop Client / Web App** sử dụng REST API (hoặc SDK) kết nối với Server với token.
+2. 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.
+3. 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`.
+4. **Redis** đóng vai trò Pub/Sub để push event qua WebSockets/GraphQL Subscriptions tới các client đang online (Realtime Updates).
+5. 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)](./server/README.md)
+- [Frontend (Vue/Nuxt 3)](./frontend/README.md)
+- [Microservices (File import, Webhook, Preview)](./services/README.md)
+- [Core 3D Engine (Viewer)](./viewer/README.md)
+
+## 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:
+  1. Kế thừa chuẩn xác thuật toán Hash Object của Speckle (để objectId luôn khớp).
+  2. Maintain được cấu trúc Database Schema (hoặc tự chuyển đổi Data Mapper hiệu quả).
+  3. 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.

docs/audit_report.md

@@ -0,0 +1,28 @@
+# 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.*

docs/frontend/README.md

@@ -0,0 +1,26 @@
+# Frontend Architecture (Speckle Web)
+
+Speckle Frontend (tại `packages/frontend-2`) là ứng dụng web tương tác chính để người dùng có thể quản lý, cấp quyền và xem các mô hình 3D trên nền web.
+
+## 1. Công nghệ sử dụng
+- **Framework:** Vue 3 + Nuxt 3 (SSR + Composition API). Hỗ trợ Server-Side Rendering giúp cải thiện SEO (ví dụ các model public có thể crawl được), đồng thời cải thiện First Contentful Paint.
+- **State & Data Fetching:** `@vue/apollo-composable`, `@apollo/client`. Gần như **không có store cục bộ/Redux/Pinia** phức tạp. Speckle dùng ngay bộ [Apollo InMemoryCache] làm Single Source of Truth cho dữ liệu, kết hợp với Vue Composables để cung cấp reactivity.
+- **UI & Styling:** Tailwind CSS v3 (`@tailwindcss/...`), Headless UI (`@headlessui/vue`) cho accessible components, các components tái sử dụng nằm ở `packages/ui-components`.
+- **Editor:** Tiptap cho trình soạn thảo comment (Rich text format).
+- **GraphQL Codegen:** Dùng `@graphql-codegen` để tự động sinh Data Type TypeScript từ file gql nhằm đồng bộ hoá Type từ Server -> Frontend.
+
+## 2. Kiến trúc Data Flow
+1. **SSR Fetching**: Khi gọi các URL chứa Model ID cụ thể (ví dụ `/projects/abc/models/xyz`), Nuxt Server sẽ gọi GraphQL về backend để lấy cấu trúc dữ liệu Metadata của file 3D.
+2. **Viewer Mount (Client Only)**: Việc xử lý Load 3D WebGL chỉ diễn ra ở phía Browser. Module `@speckle/viewer` được mount vào và khởi tạo `Streaming Object Loader`.
+3. **Lazy Loading 3D Objects**: Thay vì fetch về 1 cục khổng lồ, Apollo/Viewer sẽ stream objects dạng mảng (arrays of nested buffers) qua REST API `/objects/`.
+
+## 3. Quản lý Component Design
+- Tailwind Config của `frontend-2` kế thừa từ `@speckle/tailwind-theme` (Monorepo Workspace).
+- Bạn sẽ ít thấy `<style scoped>`. Đa phần dùng Utility classes của Tailwind. Do đó, quy tắc Design tokens rất nghiêm ngặt.
+
+## 4. Portability Note (Chuyển ngữ/Rewrite)
+- **Rất khó:** Do hệ sinh thái Vue 3 Nuxt 3 và `@speckle/viewer` (được xây dựng trên môi trường JavaScript API) có sự kết dính chặt chẽ.
+- **Hướng giải quyết nếu đổi công nghệ (VD chuyển sang React/Next.js)**:
+  1. Giữ nguyên 100% `@speckle/viewer` gốc (nó là vanilla JS/ThreeJS, có thể wrap bởi `useEffect`/`useRef` bên React).
+  2. Bưng nguyên bộ GraphQL Schema và dùng `@apollo/client` bên React.
+  3. Cấp phát đúng cấu trúc Token & Auth JWT tương đương vì viewer đòi hỏi Auth Token để load file Private.

docs/llms.txt

@@ -0,0 +1,13 @@
+# Speckle Server Docs
+
+> Đây là file định tuyến cho các hệ thống LLMs/AI Agent đọc vào dự án.
+
+## Core Conceptual Files
+- [Architecture & Core Concepts](./README.md): Giải thích Stream, Branch, Commit, Object.
+- [Backend GraphQL & Modules](./server/README.md): Node.js Express server logic & Postgres structure.
+- [Frontend Nuxt 3](./frontend/README.md): Vue 3 structure.
+- [Microservices](./services/README.md): Background jobs (webhook, preview, fileimport).
+- [Viewer & Objectloader](./viewer/README.md): 3D Streaming via Three.js.
+
+## Data Philosophy
+Speckle là *Object-based Hub*. File 3D (Revit, Rhino) được plugin Speckle đập vỡ thành hàng triệu JSON/Object nodes (ví dụ: từng Cửa sổ, Cái ghế đóng vai trò một UUID riêng). Thay vì lưu file, Speckle lưu cây JSON khổng lồ (Directed Acyclic Graph). Do đó, nó có thể diff commit (so sánh sự thay đổi của thiết kế) một cách hoàn hảo.

docs/server/README.md

@@ -0,0 +1,35 @@
+# Backend Architecture (Speckle Server)
+
+Đây là tài liệu phân tích kỹ thuật Backend của Speckle. 
+
+## 1. Công nghệ sử dụng
+- **Runtime:** Node.js (V12+ theo doc, nhưng hiện tại đã nâng cấp v22.17). Môi trường ESM (`type: "module"`).
+- **Core server Framework:** Express
+- **API Protocol:** GraphQL thông qua `@apollo/server`.
+- **Database:** PostgreSQL (Driver `pg`), dùng Query Builder `knex`. **Speckle không dùng ORM** (như TypeORM/Prisma) mà dùng `knex` để tối ưu performance cho các câu query phức tạp với cấu trúc đồ thị.
+- **Caching & Pub/Sub:** Redis (qua thư viện `ioredis`), `graphql-redis-subscriptions`.
+- **Background Jobs:** Sử dụng `bull` cho Queues (Notifications, Webhooks events).
+- **Blob storage:** AWS S3 SDK (`@aws-sdk/client-s3`), kết nối với MinIO.
+
+## 2. Tổ chức thư mục (Modular Monolith)
+Backend không chia thành microservices độc lập mà dùng cấu trúc **Modular Monolith** trong thư mục `packages/server/modules`. Mỗi module (như `core`, `auth`, `webhooks`) thường có:
+1. `index.ts/js`: Expose 2 hàm bắt buộc `init` và `finalize` (được gọi ở vòng đời khởi động server).
+2. `graph/`: Chứa `schemas` (các file `.graphql`) và `resolvers/` (logic resolver thực tế). Resolvers tự động được hệ thống merge lại ở hàm root để sinh ra 1 GraphQL Schema khổng lồ.
+3. `services/` hoặc `repositories/`: Database calls qua `knex`.
+4. `rest/`: (Tuỳ chọn) Chứa các REST API upload/download file thô siêu tốc - tối ưu không tải qua bộ nhớ GraphQL.
+
+## 3. Database Design (Nguyên tắc thiết kế Knex + Postgres)
+- **Streams / Branches / Commits**: Các Node chính quan trọng. Postgres làm rất tốt việc lưu trữ relation logic giữa Commit -> Branch -> Stream.
+- **Objects**: Mọi dữ liệu băm được lưu vào một bảng `objects`. Các Objects liên kết chéo với nhau. ID của Object lấy cấu trúc Hash của Data bên trong nó (SHA256). Điều này có nghĩa nếu Payload nội dung không đổi, ID sẽ tái sử dụng -> Tránh trùng lặp CSQL (Data Deduplication). Lỗi lớn nhất khi chuyển ngữ (Port) backend này sang Golang/C# là việc không sao chép được chính xác thuật toán Hash object này.
+
+## 4. GraphQL API & Federation
+- Mọi logic query diễn ra tại graph. Hệ thống dùng `bull` queue ngầm. 
+- Dữ liệu Push/Pull nặng (Data Stream Pipeline) không đi qua GraphQL Resolvers, mà được Speckle xây dựng REST API riêng (`/objects/...`) kết hợp Streaming (`busboy`) để đẩy thẳng Node Buffer Stream từ Web lên S3/Database mà không làm ngập RAM máy chủ V8 Heap.
+- Khi port sang ngôn ngữ khác, **bạn hoàn toàn có thể chuyển GraphQL -> REST/gRPC**, chỉ là frontend hiện tại đang gắn chặt với schema GraphQL.
+
+## 5. Flow Authentication
+- Kết hợp `passport` (Local, Github, AzureAD,...), JWT và PAC (Personal Access Tokens).
+
+## Khuyến nghị từ Backend Specialist khi Audit / Porting
+1. **Lưu ý Memory leak / Bounded RAM**: Việc parse 1 request JSON khổng lồ (>500MB) trên Nodejs dễ dẫn đến Out of memory. Server Speckle giải quyết bằng việc parse theo Stream (`pg-query-stream`). Ngôn ngữ mới thay thế (Rust/Go) sẽ làm điều này tốt hơn và sử dụng ít RAM hơn rất nhiều.
+2. **Database Migration**: `knex` lưu lại migration state trong db. Bất cứ ngôn ngữ thay thế nào cũng sẽ cần mapping tay các SQL migration này qua file `.sql` chuẩn (Planetscale / Atlas) nếu không giữ `knex`.

docs/services/README.md

@@ -0,0 +1,36 @@
+# 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).

docs/viewer/README.md

@@ -0,0 +1,28 @@
+# Viewer & Objectloader Architecture
+
+Đây là tài liệu tập trung vào trái tim của Speckle Web: Bộ hiển thị 3D (Viewer) và luồng tải dữ liệu (Objectloader).
+
+## 1. Công nghệ sử dụng
+- **Engine chính**: `three` (Three.js v0.140.0+).
+- **Hỗ trợ hình học toán học & xử lý lưới (Mesh processing)**:
+  - `three-mesh-bvh` (Tính toán giao cắt Raycasting siêu tốc cho mô hình hàng triệu polygon).
+  - `earcut` & `polylabel` (Polygon triangulation & tính toán tâm cho bề mặt).
+- **Render Text (Chữ trong 3D)**: `troika-three-text`.
+- **Dữ liệu mảng (Data Streaming)**: `@speckle/objectloader2` (Được viết bằng plain TypeScript).
+
+## 2. Objectloader (Giải mã Data Stream)
+- Speckle KHÔNG gửi toàn bộ model 1 file `.obj` hay `.gltf` xuống client. Thay vào đó, API trả về 1 mảng các Object hashes.
+- `Objectloader` chịu trách nhiệm gọi API `/objects/` theo lô. Khi dữ liệu dạng Hash array về, nó giải nén và reconstruct (tái tạo lại) thành cây JSON theo đúng cấu trúc hình học.
+- Dữ liệu này sau đó đẩy vào chuỗi queue cho Viewer đọc.
+
+## 3. Viewer Core (Architecture)
+1. **Converter/Parsers**: Trong viewer có các modules nhỏ nhận JSON từ Objectloader và dịch sang Geometry (`BufferGeometry` của Three.js). Do dữ liệu kiến trúc (BIM/CAD) rất đa dạng (Curves, Meshes, Breps, Points), Viewer có parser riêng cho từng loại data.
+2. **Batching & Instancing**: Để render một tòa nhà 50.000 cái cửa sổ mà không làm lag trình duyệt web, Viewer thực hiện **Mesh Batching** hoặc **InstancedMesh**. Nghĩa là nó gộp tất cả các object có cùng vật liệu (material) vào chung 1 lưới Draw Call.
+3. **Filtering & Coloring**: Viewer cung cấp API rất xịn xò để áp màu sắc dựa trên thuộc tính metadata (Ví dụ: tô màu tường theo Category tường, Cột theo Category cột). Kỹ thuật này đổi màu tại Shader hoặc thay đổi vertex colors trực tiếp trên Buffer.
+4. **Selections (Raycasting)**: Sử dụng BVH (`three-mesh-bvh`) nên tốc độ click chọn trúng 1 Object trong hàng triệu đối tượng diễn ra ở 60 FPS mà không hề giật lag.
+
+## 4. Portability Note (Nhúng vào framework khác)
+- `@speckle/viewer` được thiết kế dạng Framework-Agnostic (Không dính vào React, Vue hay Angular).
+- Nó chỉ cần nhận một `HTMLElement` container để append thẻ `<canvas>` vào.
+- Nếu muốn tích hợp lên App Mobile (React Native), hoàn toàn có thể dùng `expo-gl` và `three.js` nhưng cần tự thiết kế lại vòng lặp render, hoặc nhét Viewer vào `WebView` (cách rẻ và nhanh nhất).
+- Nếu phát hành lại Viewer hoàn toàn bằng ngôn ngữ khác (C++ / Unreal / Unity) cho Game Engine: Tham khảo kỹ logic của `Converter` trong repo này, vì đó là phép màu giúp biến chuỗi Speckle JSON thành các lưới tam giác.