# 🏗️ ARCHITECTURE — KIẾN TRÚC PHẦN MỀM & RANH GIỚI HỆ THỐNG

## 1. Bản Đồ Tổng Thể Hệ Sinh Thái (System Ecosystem)

```mermaid
graph TB
    subgraph Host ["macOS Host System (Apple Silicon)"]
        Cam["FaceTime Camera / Continuity Camera"]
        ANE["Apple Neural Engine (ANE)"]
        CG["CoreGraphics (CGEvent Mouse Synthesis)"]
    end

    subgraph HandyCore ["Handy Engine (macos-handy/) - SẢN PHẨM CHÍNH"]
        VHT["VisionHandTracker.swift<br/>(AVFoundation + VNHandPose)"]
        HG["HandGesture.swift<br/>(Gesture Taxonomy FSM)"]
        TF["EMA Smoothing Filter<br/>(Anti-Jittering)"]
        SMC["SystemMouseController.swift<br/>(Cursor Movement & Clicks)"]
        UI["SwiftUI Glass Panels & MenuBarExtra<br/>(Onboarding & Status)"]
    end

    subgraph DemoShowcase ["Demo Showcase (demos/warehouse/) - BẢN DEMO THỰC NGHIỆM"]
        HTML["index.html / 3D Diorama Showroom"]
        WebGL["Three.js PBR Renderer"]
        ECS["bitECS 0.4.0 SoA World (30Hz Tick)"]
        FF["Dijkstra FlowField Navigation O(1)"]
        Bridge["NativeEngineBridge.js<br/>(IPC 2 chiều qua window.__FULLDY__)"]
    end

    Cam --> VHT
    VHT --> ANE
    VHT --> HG
    HG --> TF
    TF --> SMC
    SMC --> CG
    VHT --> UI

    HandyCore -.->|IPC evaluateJavaScript| Bridge
    Bridge --> ECS
    Bridge --> WebGL
```

---

## 2. Ranh Giới Thư Mục (Codebase Boundary Matrix)

| Thư Mục | Ngôn Ngữ / Nền Tảng | Mục Đích | Quy Tắc Chống Lẫn Mã |
|---|---|---|---|
| **`macos-handy/`** | Swift 6.0, AppKit, SwiftUI | **Sản phẩm chính Handy**: Theo dõi cử chỉ bàn tay, điều khiển chuột, giao diện kính visionOS, Menu Bar app. | **TUYỆT ĐỐI KHÔNG** import Three.js, bitECS hay bất kỳ code nghiệp vụ kho bãi nào vào đây. Chỉ duy trì lõi hệ điều hành. |
| **`demos/warehouse/`** | JavaScript (ESM), WebGL, bitECS | **Bản demo kho hàng 3D**: Digital Twin mô phỏng luồng hàng 40.000m², thuật toán điều hướng robot, serious game. | Nằm cô lập hoàn toàn trong `demos/warehouse/`. Giao tiếp với Handy chỉ thông qua interface `NativeEngineBridge.js`. |
| **`assets/branding/`** | PNG, ICNS, ICO | Bộ nhận diện thương hiệu chuẩn Apple HIG cho Handy (`AppIcon.icns`, Menu Bar icon monochrome, banner). | Được quản lý bởi script `scripts/build-branding-assets.py`. |
| **`assets/images/` & `vendor/`** | 3D models, textures, Three.js | Tài nguyên đồ họa phục vụ bản demo và tài liệu. | Được chia sẻ tới `demos/warehouse/` thông qua symlink `demos/warehouse/assets`. |
| **`.agents/`** | Markdown | Trung tâm dữ liệu tri thức, quy tắc và ma trận vai trò cho AI Agents. | Không chứa mã nguồn thực thi độc hại. |

---

## 3. Kiến Trúc Kỹ Thuật Chi Tiết — Handy macOS Native

### A. Pipeline Thị Giác Máy Tính (Vision & ANE Pipeline)
1. **Thu nhận hình ảnh (Capture)**: `AVCaptureSession` cấu hình độ phân giải 1280x720 ở 60 FPS, định dạng `kCVPixelFormatType_420YpCbCr8BiPlanarFullRange`.
2. **Nhận diện 21 khớp xương bàn tay (Hand Pose Detection)**: Sử dụng `VNDetectHumanHandPoseRequest` của Apple Vision framework. Yêu cầu này tự động được điều hướng chạy trên **Apple Neural Engine (ANE)**, đảm bảo xử lý mỗi frame chỉ mất 2-4ms.
3. **Phân loại hình thái cử chỉ (Gesture Taxonomy State Machine)**:
   - Đo khoảng cách Euclidean giữa đầu ngón cái (`thumbTip`) và đầu ngón trỏ (`indexTip`). Khi khoảng cách $< 0.045$, kích hoạt `Air Pinch`.
   - Kiểm tra góc mở của các ngón giữa, áp út và ngón út để xác định `Index Pointer` hoặc `Open Palm`.
   - Tính toán vector vận tốc (velocity vector) của tâm bàn tay (`wrist`) để phát hiện cử chỉ vung tay nhanh (`Swipe Left/Right`).
4. **Bộ lọc khử rung nhiễu (EMA Anti-Jitter Filter)**:
   - Con trỏ chuột được làm mịn theo hàm mũ:
     $$P_{\text{smooth}}(t) = \alpha \cdot P_{\text{raw}}(t) + (1 - \alpha) \cdot P_{\text{smooth}}(t - 1)$$
   - Hệ số $\alpha$ thích ứng động: Khi tay di chuyển nhanh thì $\alpha \approx 0.8$ (độ trễ bằng 0), khi tay đứng yên để nhắm trúng nút bấm thì $\alpha \approx 0.2$ (khử rung triệt để).
5. **Điều khiển hệ thống (System Injection)**:
   - Sử dụng `CGEvent(mouseEventSource:...)` để tạo các sự kiện chuột trái, chuột di chuyển, chuột kéo thả trên toàn hệ thống macOS.

---

## 4. Kiến Trúc Bản Demo — Fulldy Warehouse 3D Showcase

### A. Mô Phỏng Dựa Trên bitECS 0.4 SoA (Structure of Arrays)
- Sử dụng TypedArrays (`Float32Array`, `Uint16Array`, `Uint8Array`) tạo thế giới mô phỏng Zero-GC, có khả năng xử lý hơn 10.000 kiện hàng và 500 robot cùng lúc tại 30 FPS cố định (Fixed-Tick 30Hz Loop).
- Thuật toán tìm đường Flow Field Dijkstra Map $O(1)$ cho phép hàng trăm robot AGV né va chạm tức thời.

### B. Cầu Nối IPC Hai Chiều (`NativeEngineBridge.js`)
- Bản demo kho hàng được chuẩn bị sẵn sàng để nhúng vào cửa sổ WKWebView của ứng dụng macOS hoặc chạy độc lập trên trình duyệt.
- Đối tượng `window.__FULLDY__` cung cấp các interface:
  - `setState('ACTIVE' | 'PAUSED' | 'THROTTLED' | 'DEEP_SLEEP')`
  - `setSpeed(multiplier)`
  - `triggerActionCard(actionType)`
- Khi người dùng thực hiện cử chỉ Air Pinch trong Handy, Swift Host có thể kích hoạt các hành động tương tác trong kho bãi 3D qua IPC bridge.