# zexrox/huntsman-synapse-web architecture

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

- Interactive diagram: https://gitdiagram.com/zexrox/huntsman-synapse-web
- Repository: https://github.com/zexrox/huntsman-synapse-web

## Overview

This is a Windows/Chrome bridge that lets Synapse Web operate a Huntsman V3 Pro TKL through a virtual HID identity while the native helper talks to the real keyboard. The main flow is Synapse Web → injected virtual HID → page relay → extension background → native host → physical HID, with replies returning through the same intermediaries. The host also translates Game Mode controls into a Windows key lock and reports Fn+F10 state back to the page. README-described setup and firmware limitations are included; sampled excerpts do not expose every host command’s implementation, so uncertain internal links are omitted.

Main entry points: [`native/host.py`](https://github.com/zexrox/huntsman-synapse-web/blob/main/native/host.py) (Feature-report bridge), [`extension/relay.js`](https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/relay.js) (Page relay), [`extension/background.js`](https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/background.js) (Native messaging), [`extension/virtual-hid.js`](https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/virtual-hid.js) (Virtual HID)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web integration"]
  node_virtual["Virtual HID<br/>[virtual-hid.js]"]
  node_bundle["Bundle compatibility<br/>[virtual-hid.js]"]
  node_gamepage["Game Mode page sync<br/>[virtual-hid.js]"]
end

subgraph group_extension["Chrome bridge"]
  node_relay["Page relay<br/>[relay.js]"]
  node_background["Native messaging<br/>[background.js]"]
end

subgraph group_native["Native helper"]
  node_host["Feature-report bridge<br/>[host.py]"]
  node_game["Game Mode lock<br/>[host.py]"]
  node_status["Diagnostics<br/>[host.py]"]
end

subgraph group_device["Keyboard and OS"]
  node_hid["HID API"]
  node_keyboard["Huntsman keyboard"]
  node_windows["Windows key hook"]
end

node_synapse(("Synapse Web"))

node_synapse -->|"uses HID"| node_virtual
node_virtual -->|"sends RPC"| node_relay
node_relay -->|"forwards requests"| node_background
node_background -->|"Native Messaging"| node_host
node_host -->|"returns replies"| node_background
node_background -->|"returns replies"| node_relay
node_relay -->|"delivers replies"| node_virtual
node_virtual -->|"patches failures"| node_bundle
node_host -->|"enumerates and opens"| node_hid
node_host -->|"forwards reports"| node_keyboard
node_hid -->|"accesses interface 3"| node_keyboard
node_host -->|"handles Game Mode"| node_game
node_game -->|"installs key hook"| node_windows
node_game -->|"publishes state"| node_background
node_background -->|"dispatches state"| node_relay
node_relay -->|"posts state"| node_gamepage
node_virtual -->|"logs notes"| node_status
node_host -->|"logs diagnostics"| node_status

click node_virtual "https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/virtual-hid.js"
click node_bundle "https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/virtual-hid.js"
click node_relay "https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/relay.js"
click node_background "https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/background.js"
click node_host "https://github.com/zexrox/huntsman-synapse-web/blob/main/native/host.py"
click node_game "https://github.com/zexrox/huntsman-synapse-web/blob/main/native/host.py"
click node_status "https://github.com/zexrox/huntsman-synapse-web/blob/main/native/host.py"
click node_gamepage "https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/virtual-hid.js"

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_virtual,node_bundle,node_gamepage toneBlue
class node_relay,node_background toneAmber
class node_host,node_game,node_status toneMint
class node_hid,node_keyboard,node_windows toneRose
class node_synapse toneIndigo
```

## Components

### Web integration

- [Virtual HID](https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/virtual-hid.js): `extension/virtual-hid.js`
- [Bundle compatibility](https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/virtual-hid.js): `extension/virtual-hid.js`
- [Game Mode page sync](https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/virtual-hid.js): `extension/virtual-hid.js`

### Chrome bridge

- [Page relay](https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/relay.js): `extension/relay.js`
- [Native messaging](https://github.com/zexrox/huntsman-synapse-web/blob/main/extension/background.js): `extension/background.js`

### Native helper

- [Feature-report bridge](https://github.com/zexrox/huntsman-synapse-web/blob/main/native/host.py): `native/host.py`
- [Game Mode lock](https://github.com/zexrox/huntsman-synapse-web/blob/main/native/host.py): `native/host.py`
- [Diagnostics](https://github.com/zexrox/huntsman-synapse-web/blob/main/native/host.py): `native/host.py`

### Keyboard and OS

- **HID API**
- **Huntsman keyboard**
- **Windows key hook**

### Other components

- **Synapse Web**

## Connections

- Synapse Web → Virtual HID: uses HID
- Virtual HID → Page relay: sends RPC
- Page relay → Native messaging: forwards requests
- Native messaging → Feature-report bridge: Native Messaging
- Feature-report bridge → Native messaging: returns replies
- Native messaging → Page relay: returns replies
- Page relay → Virtual HID: delivers replies
- Virtual HID → Bundle compatibility: patches failures
- Feature-report bridge → HID API: enumerates and opens
- Feature-report bridge → Huntsman keyboard: forwards reports
- HID API → Huntsman keyboard: accesses interface 3
- Feature-report bridge → Game Mode lock: handles Game Mode
- Game Mode lock → Windows key hook: installs key hook
- Game Mode lock → Native messaging: publishes state
- Native messaging → Page relay: dispatches state
- Page relay → Game Mode page sync: posts state
- Virtual HID → Diagnostics: logs notes
- Feature-report bridge → Diagnostics: logs diagnostics