# todomagichere/handsfree-pong architecture

> Architecture diagram of the GitHub repository todomagichere/handsfree-pong, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/todomagichere/handsfree-pong
- Repository: https://github.com/todomagichere/handsfree-pong

## Overview

##### Main components
- Browser/User Interface: Represented by index.html which is the entry point of the application.
- Game Logic & Controller: The custom handsfree.js acts as the controller for the game’s logic and user input processing.
- Hand Tracking Engine: The assets folder, in particular the assets/@mediapipe/hands and drawing_utils.js, which provide the configuration and functionality for detecting hand gestures.
- External Libraries/Assets: Although the project is largely self-contained, the MediaPipe binaries, WASM files, and JavaScript within the assets directory serve as the important libraries handling the machine perception (hand detection).

##### Relationships and interactions between components
- The index.html loads and initiates handsfree.js and possibly references the MediaPipe assets.
- handsfree.js acts as the orchestrator: it uses the MediaPipe libraries and WASM modules to process live camera data (hand tracking input) and converts those inputs into game controls.
- The MediaPipe (assets) components perform the hand detection and return data that the handsfree.js uses to control the game state (paddle movement, game start, etc.).
- The data flow goes from the user’s camera to the MediaPipe components (hand detection) and then on to the game logic (handling game rules, collision detection, etc.), finally producing visual feedback rendered in the browser.

##### Important architectural patterns or design principles
- Client-Side Application: All logic runs within the browser, eliminating the need for server-side interactions.
- Modular Design: The directory structure separates the core game logic (handsfree.js and index.html) from the integrated hand-tracking assets.
- Dependency Injection & Separation of Concerns: MediaPipe assets are cleanly integrated as external dependencies, allowing handsfree.js to focus solely on translating detection results into game actions.

##### Including relevant technologies and notable libraries
- HTML5 for the index page.
- JavaScript for the game logic and MediaPipe integrations.
- WebAssembly (WASM): The mediapipe asset (hands_solution_simd_wasm_bin.wasm) provides performance enhancements in hand detection.
- MediaPipe’s JavaScript libraries for hand detection through assets/@mediapipe.

##### Additional Details
- Don’t hesitate to further break down the handsfree.js module into sub-components if the actual code reveals distinct responsibilities (such as input handling, collision detection, rendering engine, etc.), but for now, a high-level breakdown is sufficient.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("User Camera (Webcam Input)"):::input
    B("Browser UI (index.html)"):::ui
    C("Game Logic Controller (handsfree.js)"):::logic
    subgraph "MediaPipe Hand Tracking Module"
        D("MediaPipe Hands"):::handtrack
        E("MediaPipe Drawing Utils"):::handtrack
    end
    F("External Libraries/Assets"):::external

    A -->|"captures"| D
    A -->|"captures"| E
    F -->|"provides"| D
    F -->|"provides"| E
    D -->|"detection_output"| C
    C -->|"renders_updates"| B

    click B "https://github.com/todomagichere/handsfree-pong/blob/main/index.html"
    click C "https://github.com/todomagichere/handsfree-pong/blob/main/handsfree.js"
    click D "https://github.com/todomagichere/handsfree-pong/tree/main/assets/@mediapipe/hands"
    click E "https://github.com/todomagichere/handsfree-pong/blob/main/assets/@mediapipe/drawing_utils.js"
    click F "https://github.com/todomagichere/handsfree-pong/tree/main/assets"

    classDef input fill:#FFF3B0,stroke:#333,stroke-width:2px;
    classDef ui fill:#A2D2FF,stroke:#333,stroke-width:2px;
    classDef logic fill:#CFFFD0,stroke:#333,stroke-width:2px;
    classDef handtrack fill:#FFADAD,stroke:#333,stroke-width:2px;
    classDef external fill:#FFD6A5,stroke:#333,stroke-width:2px;
```
