# 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.