# kartik13-op/mobile-gamepad architecture

> Architecture diagram of the GitHub repository kartik13-op/mobile-gamepad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kartik13-op/mobile-gamepad
- Repository: https://github.com/kartik13-op/mobile-gamepad

## Overview

TouchKeys is a Windows virtual gamepad controlled from a phone browser over a local network. The principal workflow runs from the desktop monitor starting the phone server, through the phone’s WebSocket input, to local event routing and Windows input. The README documents the layout editor, multi-client slots, and optional screen streaming; those branches are included. Unsampled implementation details are represented only where documented, and edges use README or excerpt evidence.

Main entry points: [`backend/server.py`](https://github.com/kartik13-op/mobile-gamepad/blob/main/backend/server.py) (HTTP and WebSocket server), [`static/js/app.js`](https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/app.js) (Client app startup), [`controller/events.py`](https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/events.py) (Input event router), [`static/js/websocket.js`](https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/websocket.js) (WebSocket client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop and Servers"]
  node_gui["Desktop control center<br/>[gui.py]"]
  node_server["HTTP and WebSocket server<br/>[server.py]"]
  node_tls["LAN TLS certificate<br/>[tls.py]"]
end

subgraph group_browser["Phone and Monitor UI"]
  node_mobilepage["Controller page<br/>[mobile.html]"]
  node_monitorpage["Monitor page<br/>[monitor.html]"]
  node_app["Client app startup<br/>[app.js]"]
  node_websocket["WebSocket client<br/>[websocket.js]"]
  node_gamepadui["Touch controls<br/>[controller.js]"]
  node_layoutui["Layout editor<br/>[layout.js]"]
  node_monitorui["UI and status<br/>[ui.js]"]
  node_motion["Motion controls<br/>[motion.js]"]
end

subgraph group_control["Input and Layout"]
  node_eventrouter["Input event router<br/>[events.py]"]
  node_clients["Client and slot manager<br/>[network.py]"]
  node_gamepad["Virtual gamepad output<br/>[keyboard.py]"]
  node_mouse["Mouse and keyboard output<br/>[mouse.py]"]
  node_layout["Layout management<br/>[layout.py]"]
  node_config["Controller configuration<br/>[config.py]"]
  node_storage[("JSON file storage<br/>[storage.py]")]
end

subgraph group_stream["Streaming"]
  node_streamclient["Phone stream viewer<br/>[streaming.js]"]
  node_streamserver["Screen capture and WebRTC<br/>[streaming.py]"]
end

node_operator(("PC operator"))
node_phone(("Phone browser"))
node_windows(("Windows and games"))
node_vigem["ViGEmBus driver"]

node_operator -->|"starts"| node_gui
node_gui -->|"starts locally"| node_server
node_gui -->|"prepares phone TLS"| node_tls
node_phone -->|"loads page and connects"| node_server
node_server -->|"serves"| node_mobilepage
node_server -->|"serves"| node_monitorpage
node_mobilepage -.->|"starts client"| node_app
node_app -->|"connects through"| node_websocket
node_app -->|"initializes"| node_gamepadui
node_app -->|"initializes"| node_layoutui
node_app -->|"initializes"| node_monitorui
node_gamepadui -->|"sends input"| node_websocket
node_motion -->|"sends motion"| node_websocket
node_websocket -->|"sends events"| node_server
node_server -->|"routes messages"| node_eventrouter
node_eventrouter -->|"resolves client slot"| node_clients
node_eventrouter -->|"dispatches gamepad input"| node_gamepad
node_eventrouter -->|"dispatches mouse input"| node_mouse
node_gamepad -->|"creates virtual controller"| node_vigem
node_vigem -->|"exposes XInput"| node_windows
node_mouse -->|"sends mouse and keys"| node_windows
node_layoutui -->|"exchanges layout"| node_server
node_server -->|"routes layout actions"| node_layout
node_layout -->|"loads and saves"| node_storage
node_config -->|"uses file storage"| node_storage
node_server -->|"handles stream endpoints"| node_streamserver
node_streamclient -.->|"requests stream"| node_server
node_streamserver -->|"streams desktop frames"| node_phone
node_monitorpage -->|"uses monitor endpoints"| node_server

click node_gui "https://github.com/kartik13-op/mobile-gamepad/blob/main/backend/gui.py"
click node_server "https://github.com/kartik13-op/mobile-gamepad/blob/main/backend/server.py"
click node_tls "https://github.com/kartik13-op/mobile-gamepad/blob/main/backend/tls.py"
click node_mobilepage "https://github.com/kartik13-op/mobile-gamepad/blob/main/templates/mobile.html"
click node_monitorpage "https://github.com/kartik13-op/mobile-gamepad/blob/main/templates/monitor.html"
click node_app "https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/app.js"
click node_websocket "https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/websocket.js"
click node_gamepadui "https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/controller.js"
click node_layoutui "https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/layout.js"
click node_monitorui "https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/ui.js"
click node_motion "https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/motion.js"
click node_eventrouter "https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/events.py"
click node_clients "https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/network.py"
click node_gamepad "https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/keyboard.py"
click node_mouse "https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/mouse.py"
click node_layout "https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/layout.py"
click node_config "https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/config.py"
click node_storage "https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/storage.py"
click node_streamclient "https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/streaming.js"
click node_streamserver "https://github.com/kartik13-op/mobile-gamepad/blob/main/backend/streaming.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_gui,node_server,node_tls,node_phone toneBlue
class node_mobilepage,node_monitorpage,node_app,node_websocket,node_gamepadui,node_layoutui,node_monitorui,node_motion toneAmber
class node_eventrouter,node_clients,node_gamepad,node_mouse,node_layout,node_config,node_storage toneMint
class node_streamclient,node_streamserver toneRose
class node_operator,node_windows,node_vigem toneIndigo
```

## Components

### Desktop and Servers

- [Desktop control center](https://github.com/kartik13-op/mobile-gamepad/blob/main/backend/gui.py): `backend/gui.py`
- [HTTP and WebSocket server](https://github.com/kartik13-op/mobile-gamepad/blob/main/backend/server.py): `backend/server.py`
- [LAN TLS certificate](https://github.com/kartik13-op/mobile-gamepad/blob/main/backend/tls.py): `backend/tls.py`

### Phone and Monitor UI

- [Controller page](https://github.com/kartik13-op/mobile-gamepad/blob/main/templates/mobile.html): `templates/mobile.html`
- [Monitor page](https://github.com/kartik13-op/mobile-gamepad/blob/main/templates/monitor.html): `templates/monitor.html`
- [Client app startup](https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/app.js): `static/js/app.js`
- [WebSocket client](https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/websocket.js): `static/js/websocket.js`
- [Touch controls](https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/controller.js): `static/js/controller.js`
- [Layout editor](https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/layout.js): `static/js/layout.js`
- [UI and status](https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/ui.js): `static/js/ui.js`
- [Motion controls](https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/motion.js): `static/js/motion.js`

### Input and Layout

- [Input event router](https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/events.py): `controller/events.py`
- [Client and slot manager](https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/network.py): `controller/network.py`
- [Virtual gamepad output](https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/keyboard.py): `controller/keyboard.py`
- [Mouse and keyboard output](https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/mouse.py): `controller/mouse.py`
- [Layout management](https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/layout.py): `controller/layout.py`
- [Controller configuration](https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/config.py): `controller/config.py`
- [JSON file storage](https://github.com/kartik13-op/mobile-gamepad/blob/main/controller/storage.py): `controller/storage.py`

### Streaming

- [Phone stream viewer](https://github.com/kartik13-op/mobile-gamepad/blob/main/static/js/streaming.js): `static/js/streaming.js`
- [Screen capture and WebRTC](https://github.com/kartik13-op/mobile-gamepad/blob/main/backend/streaming.py): `backend/streaming.py`

### Other components

- **PC operator**
- **Phone browser**
- **Windows and games**
- **ViGEmBus driver**

## Connections

- PC operator → Desktop control center: starts (evidence: `README.md`)
- Desktop control center → HTTP and WebSocket server: starts locally (evidence: `backend/gui.py`)
- Desktop control center → LAN TLS certificate: prepares phone TLS (evidence: `backend/gui.py`)
- Phone browser → HTTP and WebSocket server: loads page and connects (evidence: `README.md`)
- HTTP and WebSocket server → Controller page: serves (evidence: `backend/server.py`)
- HTTP and WebSocket server → Monitor page: serves (evidence: `backend/server.py`)
- Controller page → Client app startup: starts client
- Client app startup → WebSocket client: connects through (evidence: `static/js/app.js`)
- Client app startup → Touch controls: initializes (evidence: `static/js/app.js`)
- Client app startup → Layout editor: initializes (evidence: `static/js/app.js`)
- Client app startup → UI and status: initializes (evidence: `static/js/app.js`)
- Touch controls → WebSocket client: sends input (evidence: `static/js/controller.js`)
- Motion controls → WebSocket client: sends motion (evidence: `static/js/motion.js`)
- WebSocket client → HTTP and WebSocket server: sends events (evidence: `README.md`)
- HTTP and WebSocket server → Input event router: routes messages (evidence: `backend/server.py`)
- Input event router → Client and slot manager: resolves client slot (evidence: `controller/events.py`)
- Input event router → Virtual gamepad output: dispatches gamepad input (evidence: `controller/events.py`)
- Input event router → Mouse and keyboard output: dispatches mouse input (evidence: `controller/events.py`)
- Virtual gamepad output → ViGEmBus driver: creates virtual controller (evidence: `README.md`)
- ViGEmBus driver → Windows and games: exposes XInput (evidence: `README.md`)
- Mouse and keyboard output → Windows and games: sends mouse and keys (evidence: `README.md`)
- Layout editor → HTTP and WebSocket server: exchanges layout (evidence: `README.md`)
- HTTP and WebSocket server → Layout management: routes layout actions (evidence: `backend/server.py`)
- Layout management → JSON file storage: loads and saves (evidence: `controller/layout.py`)
- Controller configuration → JSON file storage: uses file storage (evidence: `controller/config.py`)
- HTTP and WebSocket server → Screen capture and WebRTC: handles stream endpoints (evidence: `backend/server.py`)
- Phone stream viewer → HTTP and WebSocket server: requests stream
- Screen capture and WebRTC → Phone browser: streams desktop frames (evidence: `README.md`)
- Monitor page → HTTP and WebSocket server: uses monitor endpoints (evidence: `README.md`)
