speckle-server/docs/server/README.md

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.