# compensis/webtypinginterface architecture

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

- Interactive diagram: https://gitdiagram.com/compensis/webtypinginterface
- Repository: https://github.com/compensis/webtypinginterface

## Overview

This firmware turns an ESP32-S3 into a browser-driven USB keyboard. A browser loads the embedded page over HTTP, connects over WebSocket, and sends physical-key HID codes plus modifier bits; the firmware converts each packet into a keyboard report for the USB host. A separate status path reports USB mount state to the browser. The README documents key coverage, layout-independent input, Wi-Fi, mDNS, and serial diagnostics. The HTML and firmware entry point are present in the tree; the page source was not sampled, so browser behavior is based on README documentation.

Main entry points: [`src/main.cpp`](https://github.com/compensis/webtypinginterface/blob/main/src/main.cpp) (Firmware loop), [`lib/USBBootKeyboard/src/USBHID.cpp`](https://github.com/compensis/webtypinginterface/blob/main/lib/USBBootKeyboard/src/USBHID.cpp) (HID transport), [`lib/USBBootKeyboard/src/USBHIDKeyboard.cpp`](https://github.com/compensis/webtypinginterface/blob/main/lib/USBBootKeyboard/src/USBHIDKeyboard.cpp) (Keyboard reports), [`src/index.html`](https://github.com/compensis/webtypinginterface/blob/main/src/index.html) (Typing page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser interface"]
  node_webpage["Typing page<br/>[index.html]"]
  node_browser(("Browser keyboard"))
end

subgraph group_firmware["ESP32 firmware"]
  node_main["Firmware loop<br/>[main.cpp]"]
  node_http["HTTP server<br/>[main.cpp]"]
  node_ws["WebSocket server<br/>[main.cpp]"]
  node_mdns["mDNS advertiser<br/>[main.cpp]"]
end

subgraph group_hid["USB HID stack"]
  node_hidkeyboard["Keyboard reports<br/>[USBHIDKeyboard.cpp]"]
  node_usbcore["HID transport<br/>[USBHID.cpp]"]
end

subgraph group_network["Network services"]
  node_wifi{{"Wi-Fi network"}}
end

node_user(("Browser user"))
node_usbhost(("USB host"))
node_serial(("Serial monitor"))

node_user -->|"opens page"| node_browser
node_browser -->|"requests page"| node_http
node_http -->|"serves HTML"| node_webpage
node_browser -->|"sends HID packet"| node_ws
node_ws -->|"submits report"| node_hidkeyboard
node_hidkeyboard -->|"sends report"| node_usbcore
node_usbcore -->|"USB HID reports"| node_usbhost
node_main -->|"checks mount state"| node_usbcore
node_main -->|"broadcasts status"| node_ws
node_usbhost -->|"mount state"| node_main
node_main -->|"connects"| node_wifi
node_main -->|"starts advertisement"| node_mdns
node_browser -.->|"resolves hostname"| node_mdns
node_main -->|"prints diagnostics"| node_serial

click node_webpage "https://github.com/compensis/webtypinginterface/blob/main/src/index.html"
click node_main "https://github.com/compensis/webtypinginterface/blob/main/src/main.cpp"
click node_http "https://github.com/compensis/webtypinginterface/blob/main/src/main.cpp"
click node_ws "https://github.com/compensis/webtypinginterface/blob/main/src/main.cpp"
click node_hidkeyboard "https://github.com/compensis/webtypinginterface/blob/main/lib/USBBootKeyboard/src/USBHIDKeyboard.cpp"
click node_usbcore "https://github.com/compensis/webtypinginterface/blob/main/lib/USBBootKeyboard/src/USBHID.cpp"
click node_mdns "https://github.com/compensis/webtypinginterface/blob/main/src/main.cpp"

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_webpage,node_browser,node_user toneBlue
class node_main,node_http,node_ws,node_mdns toneAmber
class node_hidkeyboard,node_usbcore toneMint
class node_wifi toneRose
class node_usbhost,node_serial toneIndigo
```

## Components

### Browser interface

- [Typing page](https://github.com/compensis/webtypinginterface/blob/main/src/index.html): `src/index.html`
- **Browser keyboard**

### ESP32 firmware

- [Firmware loop](https://github.com/compensis/webtypinginterface/blob/main/src/main.cpp): `src/main.cpp`
- [HTTP server](https://github.com/compensis/webtypinginterface/blob/main/src/main.cpp): `src/main.cpp`
- [WebSocket server](https://github.com/compensis/webtypinginterface/blob/main/src/main.cpp): `src/main.cpp`
- [mDNS advertiser](https://github.com/compensis/webtypinginterface/blob/main/src/main.cpp): `src/main.cpp`

### USB HID stack

- [Keyboard reports](https://github.com/compensis/webtypinginterface/blob/main/lib/USBBootKeyboard/src/USBHIDKeyboard.cpp): `lib/USBBootKeyboard/src/USBHIDKeyboard.cpp`
- [HID transport](https://github.com/compensis/webtypinginterface/blob/main/lib/USBBootKeyboard/src/USBHID.cpp): `lib/USBBootKeyboard/src/USBHID.cpp`

### Network services

- **Wi-Fi network**

### Other components

- **Browser user**
- **USB host**
- **Serial monitor**

## Connections

- Browser user → Browser keyboard: opens page
- Browser keyboard → HTTP server: requests page
- HTTP server → Typing page: serves HTML
- Browser keyboard → WebSocket server: sends HID packet
- WebSocket server → Keyboard reports: submits report
- Keyboard reports → HID transport: sends report
- HID transport → USB host: USB HID reports
- Firmware loop → HID transport: checks mount state
- Firmware loop → WebSocket server: broadcasts status
- USB host → Firmware loop: mount state
- Firmware loop → Wi-Fi network: connects
- Firmware loop → mDNS advertiser: starts advertisement
- Browser keyboard → mDNS advertiser: resolves hostname
- Firmware loop → Serial monitor: prints diagnostics