speckle-server/docs/frontend/README.md

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.