# frogcaller/ha-gesture-remote architecture

> Architecture diagram of the GitHub repository frogcaller/ha-gesture-remote, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/frogcaller/ha-gesture-remote
- Repository: https://github.com/frogcaller/ha-gesture-remote

## Overview

This is a single-file, local webcam gesture remote for Home Assistant. The main workflow is camera frames → hand tracking and gesture interpretation → configurable action mapping → Home Assistant commands for media-player or remote entities; the app also displays camera/video feedback. Setup connects to Home Assistant to discover entities and save configuration, while runtime controls support remapping and multiple cameras. The tree contains only one runtime source file, so distinct responsibilities share its path. The sampled excerpts are partial; links reflect the README’s documented workflow and avoid assuming finer internal call order.

Main entry points: [`ha_gesture_remote.py`](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py) (HA service client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and settings"]
  node_setup_ui["Setup UI"]
  node_config["Config read/write"]
  node_entity_discovery["Entity discovery"]
  node_remap_ui["Gesture remapping"]
end

subgraph group_vision["Camera and gestures"]
  node_camera_sources["Camera sources"]
  node_hand_tracking["Hand tracking"]
  node_gesture_detection["Gesture detection"]
  node_multi_camera["Camera selection"]
end

subgraph group_runtime["Remote runtime"]
  node_gesture_mapping["Action mapping"]
  node_remote_loop["Remote control loop"]
  node_ha_client["HA service client"]
  node_command_queue["Command queue"]
  node_media_player["Media-player control"]
  node_remote_entity["D-pad remote control"]
  node_video_feedback["Video feedback"]
end

node_user(("User"))
node_camera["Webcam"]
node_ha["Home Assistant"]
node_tv["TV"]

node_user -->|"configures"| node_setup_ui
node_setup_ui -->|"connects"| node_ha_client
node_ha_client -->|"queries entities"| node_ha
node_ha -->|"returns entities"| node_entity_discovery
node_entity_discovery -->|"fills selectors"| node_setup_ui
node_setup_ui -->|"saves settings"| node_config
node_config -->|"loads settings"| node_remote_loop
node_camera -->|"provides frames"| node_camera_sources
node_camera_sources -->|"supplies frames"| node_hand_tracking
node_hand_tracking -->|"provides landmarks"| node_gesture_detection
node_camera_sources -->|"provides views"| node_multi_camera
node_multi_camera -->|"selects view"| node_gesture_detection
node_gesture_detection -->|"identifies gestures"| node_gesture_mapping
node_user -->|"opens remapping"| node_remap_ui
node_remap_ui -->|"saves mappings"| node_config
node_gesture_mapping -->|"selects action"| node_remote_loop
node_user -->|"uses controls"| node_remote_loop
node_remote_loop -->|"queues commands"| node_command_queue
node_command_queue -->|"dispatches commands"| node_ha_client
node_ha_client -->|"calls services"| node_media_player
node_ha_client -->|"calls services"| node_remote_entity
node_media_player -->|"targets entity"| node_ha
node_remote_entity -->|"targets entity"| node_ha
node_ha -->|"controls"| node_tv
node_remote_loop -->|"updates display"| node_video_feedback

click node_setup_ui "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_config "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_entity_discovery "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_remap_ui "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_camera_sources "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_hand_tracking "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_gesture_detection "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_multi_camera "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_gesture_mapping "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_remote_loop "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_ha_client "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_command_queue "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_media_player "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_remote_entity "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"
click node_video_feedback "https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_setup_ui,node_config,node_entity_discovery,node_remap_ui,node_user toneBlue
class node_camera_sources,node_hand_tracking,node_gesture_detection,node_multi_camera toneAmber
class node_gesture_mapping,node_remote_loop,node_ha_client,node_command_queue,node_media_player,node_remote_entity,node_video_feedback toneMint
class node_camera,node_ha,node_tv toneIndigo
```

## Components

### Setup and settings

- [Setup UI](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`
- [Config read/write](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`
- [Entity discovery](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`
- [Gesture remapping](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`

### Camera and gestures

- [Camera sources](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`
- [Hand tracking](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`
- [Gesture detection](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`
- [Camera selection](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`

### Remote runtime

- [Action mapping](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`
- [Remote control loop](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`
- [HA service client](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`
- [Command queue](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`
- [Media-player control](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`
- [D-pad remote control](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`
- [Video feedback](https://github.com/frogcaller/ha-gesture-remote/blob/main/ha_gesture_remote.py): `ha_gesture_remote.py`

### Other components

- **User**
- **Webcam**
- **Home Assistant**
- **TV**

## Connections

- User → Setup UI: configures
- Setup UI → HA service client: connects
- HA service client → Home Assistant: queries entities
- Home Assistant → Entity discovery: returns entities
- Entity discovery → Setup UI: fills selectors
- Setup UI → Config read/write: saves settings
- Config read/write → Remote control loop: loads settings
- Webcam → Camera sources: provides frames
- Camera sources → Hand tracking: supplies frames
- Hand tracking → Gesture detection: provides landmarks
- Camera sources → Camera selection: provides views
- Camera selection → Gesture detection: selects view
- Gesture detection → Action mapping: identifies gestures
- User → Gesture remapping: opens remapping
- Gesture remapping → Config read/write: saves mappings
- Action mapping → Remote control loop: selects action
- User → Remote control loop: uses controls
- Remote control loop → Command queue: queues commands
- Command queue → HA service client: dispatches commands
- HA service client → Media-player control: calls services
- HA service client → D-pad remote control: calls services
- Media-player control → Home Assistant: targets entity
- D-pad remote control → Home Assistant: targets entity
- Home Assistant → TV: controls
- Remote control loop → Video feedback: updates display