# matthew-the-great/arena-timer-emulator architecture

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

- Interactive diagram: https://gitdiagram.com/matthew-the-great/arena-timer-emulator
- Repository: https://github.com/matthew-the-great/arena-timer-emulator

## Overview

ArenaTimer is a Windows-hosted ESP32 emulator dashboard, with a separate optional behavioral simulator. The main emulator workflow is: upload a complete flash image, start the virtual ESP32, relay its guest web interface, and view guest-sourced timer and LED output while sending controls. The behavioral simulator instead drives a native firmware process and presents its state in a separate dashboard. README documents Wi-Fi/NAT, UART controls, and raw or synchronized LED display; some QEMU startup and simulator command wiring is not visible in the excerpts, so those links are omitted or marked unverified.

Main entry points: [`public/qemu.js`](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/public/qemu.js) (Emulator UI), [`qemu/manager.mjs`](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/qemu/manager.mjs) (QEMU Manager), [`server.mjs`](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/server.mjs) (HTTP Server), [`engine.mjs`](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/engine.mjs) (Process Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sim_ui["Behavioral Dashboard"]
  node_sim_page["Simulator Page<br/>[index.html]"]
  node_sim_controls["Simulator UI<br/>[sim.js]"]
end

subgraph group_sim_runtime["Behavioral Runtime"]
  node_http_server["HTTP Server<br/>[server.mjs]"]
  node_engine["Process Engine<br/>[engine.mjs]"]
  node_native_firmware["Native Firmware Host<br/>[host.cpp]"]
end

subgraph group_emu_ui["ESP32 Dashboard"]
  node_qemu_page["Emulator Page<br/>[qemu.html]"]
  node_qemu_controls["Emulator UI<br/>[qemu.js]"]
  node_led_display["LED Display<br/>[qemu.js]"]
end

subgraph group_emu_runtime["ESP32 Emulation"]
  node_qemu_api["QEMU Manager<br/>[manager.mjs]"]
  node_led_validator["LED Frame Validator<br/>[led-frames.mjs]"]
  node_qemu_process["ESP32 QEMU"]
end

subgraph group_guest_network["Guest Network and Display"]
  node_guest_relay["Guest HTTP Relay<br/>[network.mjs]"]
  node_guest_html["Guest Page Adapter<br/>[guest-display.mjs]"]
  node_guest_firmware["User Firmware Interface"]
end

node_user(("Operator"))

node_user -->|"opens"| node_sim_page
node_sim_page -->|"loads"| node_sim_controls
node_sim_controls -->|"posts actions"| node_http_server
node_http_server -.->|"creates and drives"| node_engine
node_engine -->|"spawns process"| node_native_firmware
node_native_firmware -->|"emits state"| node_engine
node_user -->|"opens"| node_qemu_page
node_qemu_page -->|"loads"| node_qemu_controls
node_qemu_controls -->|"uploads and controls"| node_qemu_api
node_http_server -->|"routes requests"| node_qemu_api
node_qemu_api -->|"validates frames"| node_led_validator
node_qemu_api -->|"creates relay"| node_guest_relay
node_qemu_controls -->|"renders frames"| node_led_display
node_qemu_api -.->|"manages process"| node_qemu_process
node_qemu_controls -->|"opens guest page"| node_guest_relay
node_guest_relay -->|"proxies requests"| node_guest_firmware
node_guest_firmware -->|"HTML adapted by relay"| node_guest_html
node_guest_html -->|"posts timer value"| node_qemu_controls

click node_sim_page "https://github.com/matthew-the-great/arena-timer-emulator/blob/main/public/index.html"
click node_sim_controls "https://github.com/matthew-the-great/arena-timer-emulator/blob/main/public/sim.js"
click node_http_server "https://github.com/matthew-the-great/arena-timer-emulator/blob/main/server.mjs"
click node_engine "https://github.com/matthew-the-great/arena-timer-emulator/blob/main/engine.mjs"
click node_native_firmware "https://github.com/matthew-the-great/arena-timer-emulator/blob/main/native/host.cpp"
click node_qemu_page "https://github.com/matthew-the-great/arena-timer-emulator/blob/main/public/qemu.html"
click node_qemu_controls "https://github.com/matthew-the-great/arena-timer-emulator/blob/main/public/qemu.js"
click node_qemu_api "https://github.com/matthew-the-great/arena-timer-emulator/blob/main/qemu/manager.mjs"
click node_led_validator "https://github.com/matthew-the-great/arena-timer-emulator/blob/main/qemu/led-frames.mjs"
click node_guest_relay "https://github.com/matthew-the-great/arena-timer-emulator/blob/main/qemu/network.mjs"
click node_guest_html "https://github.com/matthew-the-great/arena-timer-emulator/blob/main/qemu/guest-display.mjs"
click node_led_display "https://github.com/matthew-the-great/arena-timer-emulator/blob/main/public/qemu.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_sim_page,node_sim_controls toneBlue
class node_http_server,node_engine,node_native_firmware toneAmber
class node_qemu_page,node_qemu_controls,node_led_display toneMint
class node_qemu_api,node_led_validator,node_qemu_process toneRose
class node_guest_relay,node_guest_html,node_guest_firmware,node_user toneIndigo
```

## Components

### Behavioral Dashboard

- [Simulator Page](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/public/index.html): `public/index.html`
- [Simulator UI](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/public/sim.js): `public/sim.js`

### Behavioral Runtime

- [HTTP Server](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/server.mjs): `server.mjs`
- [Process Engine](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/engine.mjs): `engine.mjs`
- [Native Firmware Host](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/native/host.cpp): `native/host.cpp`

### ESP32 Dashboard

- [Emulator Page](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/public/qemu.html): `public/qemu.html`
- [Emulator UI](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/public/qemu.js): `public/qemu.js`
- [LED Display](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/public/qemu.js): `public/qemu.js`

### ESP32 Emulation

- [QEMU Manager](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/qemu/manager.mjs): `qemu/manager.mjs`
- [LED Frame Validator](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/qemu/led-frames.mjs): `qemu/led-frames.mjs`
- **ESP32 QEMU**

### Guest Network and Display

- [Guest HTTP Relay](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/qemu/network.mjs): `qemu/network.mjs`
- [Guest Page Adapter](https://github.com/matthew-the-great/arena-timer-emulator/blob/main/qemu/guest-display.mjs): `qemu/guest-display.mjs`
- **User Firmware Interface**

### Other components

- **Operator**

## Connections

- Operator → Simulator Page: opens (evidence: `README.md`)
- Simulator Page → Simulator UI: loads (evidence: `public/sim.js`)
- Simulator UI → HTTP Server: posts actions (evidence: `public/sim.js`)
- HTTP Server → Process Engine: creates and drives (evidence: `server.mjs`)
- Process Engine → Native Firmware Host: spawns process (evidence: `engine.mjs`)
- Native Firmware Host → Process Engine: emits state (evidence: `engine.mjs`)
- Operator → Emulator Page: opens (evidence: `README.md`)
- Emulator Page → Emulator UI: loads (evidence: `public/qemu.js`)
- Emulator UI → QEMU Manager: uploads and controls (evidence: `public/qemu.js`)
- HTTP Server → QEMU Manager: routes requests (evidence: `server.mjs`)
- QEMU Manager → LED Frame Validator: validates frames (evidence: `qemu/manager.mjs`)
- QEMU Manager → Guest HTTP Relay: creates relay (evidence: `qemu/manager.mjs`)
- Emulator UI → LED Display: renders frames (evidence: `public/qemu.js`)
- QEMU Manager → ESP32 QEMU: manages process
- Emulator UI → Guest HTTP Relay: opens guest page (evidence: `public/qemu.js`)
- Guest HTTP Relay → User Firmware Interface: proxies requests (evidence: `qemu/network.mjs`)
- User Firmware Interface → Guest Page Adapter: HTML adapted by relay
- Guest Page Adapter → Emulator UI: posts timer value (evidence: `qemu/guest-display.mjs`)