# kacperczeczot/golf-master architecture

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

- Interactive diagram: https://gitdiagram.com/kacperczeczot/golf-master
- Repository: https://github.com/kacperczeczot/golf-master

## Overview

GOLF-MASTER combines ESP32 vehicle-CAN telemetry with an offline browser dashboard. The main web workflow is BLE UART input, firmware-message or CAN-frame routing, signal decoding and state updates, then live cards, detail modals, and logs. The README documents firmware CAN reading and BLE transmission, but firmware source was not sampled, so its internal stages are not expanded. Dashboard relationships below use sampled imports and calls; other README-described capabilities are retained without guessing their internal wiring.

Main entry points: [`apps/web/js/can/frameRegistry.js`](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/can/frameRegistry.js) (Frame Registry), [`apps/web/js/shared/canUtils.js`](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/shared/canUtils.js) (Signal Utilities), [`apps/web/js/ui/modal.js`](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/ui/modal.js) (Signal Modal), [`apps/web/js/app/transport/btTerminal.js`](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/app/transport/btTerminal.js) (BLE Terminal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["ESP32 Firmware"]
  node_firmware_app["CAN Reader<br/>[esp32.ino]"]
end

subgraph group_web_runtime["Web Runtime"]
  node_web_entry["Web Bootstrap<br/>[bootstrap.js]"]
  node_bt_terminal["BLE Terminal<br/>[btTerminal.js]"]
  node_message_catalog["Message Catalog<br/>[messageCatalog.js]"]
  node_runtime_state[("Runtime State<br/>[runtimeState.js]")]
end

subgraph group_can_analysis["CAN Analysis"]
  node_frame_registry["Frame Registry<br/>[frameRegistry.js]"]
  node_comfort_decoder["Comfort Decoder<br/>[comfort.js]"]
  node_drive_decoder["Drive Decoder<br/>[drive.js]"]
  node_media_decoder["Media Decoder<br/>[media.js]"]
  node_system_decoder["System Decoder<br/>[system.js]"]
  node_can_utils["Signal Utilities<br/>[canUtils.js]"]
  node_signal_metadata["Signal Metadata<br/>[signalMeta.js]"]
end

subgraph group_dashboard["Dashboard UI"]
  node_ui_core["Frame Handler<br/>[core.js]"]
  node_ui_actions["Dashboard Actions<br/>[actions.js]"]
  node_status_logs["Status Logs<br/>[statusLogs.js]"]
  node_detail_modal["Signal Modal<br/>[modal.js]"]
  node_color_rules["Modal Color Rules<br/>[modalColorRules.js]"]
end

node_driver(("Vehicle CAN"))
node_user(("Dashboard User"))
node_ble_link["BLE UART"]

node_driver -->|"sends CAN frames"| node_firmware_app
node_firmware_app -->|"transmits BLE"| node_ble_link
node_user -->|"opens dashboard"| node_web_entry
node_web_entry -->|"initializes"| node_bt_terminal
node_web_entry -.->|"initializes UI"| node_ui_core
node_ble_link -.->|"streams telemetry"| node_bt_terminal
node_bt_terminal -->|"routes CAN frames"| node_ui_core
node_bt_terminal -->|"logs messages"| node_status_logs
node_bt_terminal -->|"resolves messages"| node_message_catalog
node_ui_core -->|"selects decoder"| node_frame_registry
node_ui_core -->|"updates frame state"| node_runtime_state
node_ui_core -->|"notifies updates"| node_detail_modal
node_frame_registry -->|"dispatches"| node_comfort_decoder
node_frame_registry -->|"dispatches"| node_drive_decoder
node_frame_registry -->|"dispatches"| node_media_decoder
node_frame_registry -->|"dispatches"| node_system_decoder
node_comfort_decoder -->|"extracts signals"| node_can_utils
node_comfort_decoder -.->|"stores decoded data"| node_runtime_state
node_drive_decoder -->|"uses signal utilities"| node_can_utils
node_media_decoder -->|"uses signal utilities"| node_can_utils
node_system_decoder -->|"uses signal utilities"| node_can_utils
node_can_utils -->|"caches frame data"| node_runtime_state
node_detail_modal -->|"reads frame data"| node_runtime_state
node_detail_modal -->|"formats signals"| node_signal_metadata
node_detail_modal -->|"formats values"| node_can_utils
node_detail_modal -->|"resolves value colors"| node_color_rules
node_ui_actions -->|"uses frame definitions"| node_frame_registry
node_ui_actions -->|"uses logging"| node_status_logs

click node_firmware_app "https://github.com/kacperczeczot/golf-master/blob/main/apps/firmware/esp32.ino"
click node_web_entry "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/app/bootstrap.js"
click node_bt_terminal "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/app/transport/btTerminal.js"
click node_message_catalog "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/app/messageCatalog.js"
click node_ui_core "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/ui/core.js"
click node_frame_registry "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/can/frameRegistry.js"
click node_comfort_decoder "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/can/decoders/comfort.js"
click node_drive_decoder "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/can/decoders/drive.js"
click node_media_decoder "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/can/decoders/media.js"
click node_system_decoder "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/can/decoders/system.js"
click node_can_utils "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/shared/canUtils.js"
click node_runtime_state "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/state/runtimeState.js"
click node_signal_metadata "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/state/signalMeta.js"
click node_ui_actions "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/ui/actions.js"
click node_status_logs "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/ui/statusLogs.js"
click node_detail_modal "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/ui/modal.js"
click node_color_rules "https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/ui/modalColors/modalColorRules.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_firmware_app,node_user toneBlue
class node_web_entry,node_bt_terminal,node_message_catalog,node_runtime_state toneAmber
class node_frame_registry,node_comfort_decoder,node_drive_decoder,node_media_decoder,node_system_decoder,node_can_utils,node_signal_metadata toneMint
class node_ui_core,node_ui_actions,node_status_logs,node_detail_modal,node_color_rules toneRose
class node_driver,node_ble_link toneIndigo
```

## Components

### ESP32 Firmware

- [CAN Reader](https://github.com/kacperczeczot/golf-master/blob/main/apps/firmware/esp32.ino): `apps/firmware/esp32.ino`

### Web Runtime

- [Web Bootstrap](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/app/bootstrap.js): `apps/web/js/app/bootstrap.js`
- [BLE Terminal](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/app/transport/btTerminal.js): `apps/web/js/app/transport/btTerminal.js`
- [Message Catalog](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/app/messageCatalog.js): `apps/web/js/app/messageCatalog.js`
- [Runtime State](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/state/runtimeState.js): `apps/web/js/state/runtimeState.js`

### CAN Analysis

- [Frame Registry](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/can/frameRegistry.js): `apps/web/js/can/frameRegistry.js`
- [Comfort Decoder](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/can/decoders/comfort.js): `apps/web/js/can/decoders/comfort.js`
- [Drive Decoder](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/can/decoders/drive.js): `apps/web/js/can/decoders/drive.js`
- [Media Decoder](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/can/decoders/media.js): `apps/web/js/can/decoders/media.js`
- [System Decoder](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/can/decoders/system.js): `apps/web/js/can/decoders/system.js`
- [Signal Utilities](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/shared/canUtils.js): `apps/web/js/shared/canUtils.js`
- [Signal Metadata](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/state/signalMeta.js): `apps/web/js/state/signalMeta.js`

### Dashboard UI

- [Frame Handler](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/ui/core.js): `apps/web/js/ui/core.js`
- [Dashboard Actions](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/ui/actions.js): `apps/web/js/ui/actions.js`
- [Status Logs](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/ui/statusLogs.js): `apps/web/js/ui/statusLogs.js`
- [Signal Modal](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/ui/modal.js): `apps/web/js/ui/modal.js`
- [Modal Color Rules](https://github.com/kacperczeczot/golf-master/blob/main/apps/web/js/ui/modalColors/modalColorRules.js): `apps/web/js/ui/modalColors/modalColorRules.js`

### Other components

- **Vehicle CAN**
- **Dashboard User**
- **BLE UART**

## Connections

- Vehicle CAN → CAN Reader: sends CAN frames (evidence: `README.md`)
- CAN Reader → BLE UART: transmits BLE (evidence: `README.md`)
- Dashboard User → Web Bootstrap: opens dashboard (evidence: `README.md`)
- Web Bootstrap → BLE Terminal: initializes (evidence: `apps/web/js/app/bootstrap.js`)
- Web Bootstrap → Frame Handler: initializes UI
- BLE UART → BLE Terminal: streams telemetry
- BLE Terminal → Frame Handler: routes CAN frames (evidence: `apps/web/js/app/transport/btTerminal.js`)
- BLE Terminal → Status Logs: logs messages (evidence: `apps/web/js/app/transport/btTerminal.js`)
- BLE Terminal → Message Catalog: resolves messages (evidence: `apps/web/js/app/transport/btTerminal.js`)
- Frame Handler → Frame Registry: selects decoder (evidence: `apps/web/js/ui/core.js`)
- Frame Handler → Runtime State: updates frame state (evidence: `apps/web/js/ui/core.js`)
- Frame Handler → Signal Modal: notifies updates (evidence: `apps/web/js/ui/core.js`)
- Frame Registry → Comfort Decoder: dispatches (evidence: `apps/web/js/can/frameRegistry.js`)
- Frame Registry → Drive Decoder: dispatches (evidence: `apps/web/js/can/frameRegistry.js`)
- Frame Registry → Media Decoder: dispatches (evidence: `apps/web/js/can/frameRegistry.js`)
- Frame Registry → System Decoder: dispatches (evidence: `apps/web/js/can/frameRegistry.js`)
- Comfort Decoder → Signal Utilities: extracts signals (evidence: `apps/web/js/can/decoders/comfort.js`)
- Comfort Decoder → Runtime State: stores decoded data
- Drive Decoder → Signal Utilities: uses signal utilities (evidence: `apps/web/js/can/decoders/drive.js`)
- Media Decoder → Signal Utilities: uses signal utilities (evidence: `apps/web/js/can/decoders/media.js`)
- System Decoder → Signal Utilities: uses signal utilities (evidence: `apps/web/js/can/decoders/system.js`)
- Signal Utilities → Runtime State: caches frame data (evidence: `apps/web/js/shared/canUtils.js`)
- Signal Modal → Runtime State: reads frame data (evidence: `apps/web/js/ui/modal.js`)
- Signal Modal → Signal Metadata: formats signals (evidence: `apps/web/js/ui/modal.js`)
- Signal Modal → Signal Utilities: formats values (evidence: `apps/web/js/ui/modal.js`)
- Signal Modal → Modal Color Rules: resolves value colors (evidence: `apps/web/js/ui/modal.js`)
- Dashboard Actions → Frame Registry: uses frame definitions (evidence: `apps/web/js/ui/actions.js`)
- Dashboard Actions → Status Logs: uses logging (evidence: `apps/web/js/ui/actions.js`)