# ruozhi67/waterctl_electron architecture

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

- Interactive diagram: https://gitdiagram.com/ruozhi67/waterctl_electron
- Repository: https://github.com/ruozhi67/waterctl_electron

## Overview

Waterctl is an Electron-enhanced Bluetooth controller for Chang Gong water-control devices. The user starts or ends a session in the renderer; the app connects over Web Bluetooth, exchanges protocol messages, handles authentication and device responses, and shows session status and a countdown. Electron automation and reconnect behavior are documented, but the Electron main/preload implementation was not excerpted, so those links are marked unverified. The PWA helper exists, but its activation in the renderer is commented out.

Main entry points: [`src/bluetooth.ts`](https://github.com/ruozhi67/waterctl_electron/blob/main/src/bluetooth.ts) (Bluetooth session), [`src/index.ts`](https://github.com/ruozhi67/waterctl_electron/blob/main/src/index.ts) (UI bootstrap), [`src/solvers.ts`](https://github.com/ruozhi67/waterctl_electron/blob/main/src/solvers.ts) (Authentication and commands), [`src/writeValueLogging.ts`](https://github.com/ruozhi67/waterctl_electron/blob/main/src/writeValueLogging.ts) (Write logging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["Renderer and session"]
  node_entry["UI bootstrap<br/>[index.ts]"]
  node_session["Bluetooth session<br/>[bluetooth.ts]"]
end

subgraph group_protocol["Device protocol"]
  node_payloads["Protocol payloads<br/>[payloads.ts]"]
  node_solvers["Authentication and commands<br/>[solvers.ts]"]
  node_algorithms["Checksums<br/>[algorithms.ts]"]
  node_wasm["Key routine<br/>[deputy.wat]"]
end

subgraph group_support["Session support"]
  node_errors["Error handling<br/>[errors.ts]"]
  node_countdown["Session countdown<br/>[Countdown.ts]"]
  node_logger["Debug log<br/>[logger.ts]"]
  node_txlog["Write logging"]
  node_utils["Byte utilities<br/>[utils.ts]"]
end

subgraph group_electron["Electron and offline"]
  node_electron_main["Electron automation<br/>[main.ts]"]
  node_preload["Renderer bridge<br/>[preload.ts]"]
  node_pwa["PWA helpers<br/>[pwaHelper.ts]"]
end

node_user(("User"))
node_device{{"Water controller"}}

node_user -->|"uses"| node_entry
node_entry -->|"registers click"| node_session
node_entry -->|"loads"| node_txlog
node_entry -->|"calls bridge"| node_preload
node_session -->|"connects and exchanges"| node_device
node_session -->|"sends protocol messages"| node_payloads
node_session -->|"builds responses"| node_solvers
node_session -->|"resolves failures"| node_errors
node_session -->|"reads and clears logs"| node_logger
node_session -->|"formats received bytes"| node_utils
node_session -->|"starts and stops"| node_countdown
node_solvers -->|"calculates checksums"| node_algorithms
node_solvers -->|"converts values"| node_utils
node_solvers -->|"uses key routine"| node_wasm
node_txlog -->|"records writes"| node_logger
node_txlog -->|"formats writes"| node_utils
node_electron_main -.-> node_preload
node_electron_main -.->|"automates connection"| node_session
node_entry -.->|"optional PWA setup"| node_pwa

click node_entry "https://github.com/ruozhi67/waterctl_electron/blob/main/src/index.ts"
click node_session "https://github.com/ruozhi67/waterctl_electron/blob/main/src/bluetooth.ts"
click node_electron_main "https://github.com/ruozhi67/waterctl_electron/blob/main/electron/main.ts"
click node_preload "https://github.com/ruozhi67/waterctl_electron/blob/main/electron/preload.ts"
click node_payloads "https://github.com/ruozhi67/waterctl_electron/blob/main/src/payloads.ts"
click node_solvers "https://github.com/ruozhi67/waterctl_electron/blob/main/src/solvers.ts"
click node_algorithms "https://github.com/ruozhi67/waterctl_electron/blob/main/src/algorithms.ts"
click node_wasm "https://github.com/ruozhi67/waterctl_electron/blob/main/src/deputy.wat"
click node_errors "https://github.com/ruozhi67/waterctl_electron/blob/main/src/errors.ts"
click node_countdown "https://github.com/ruozhi67/waterctl_electron/blob/main/src/Countdown.ts"
click node_logger "https://github.com/ruozhi67/waterctl_electron/blob/main/src/logger.ts"
click node_txlog "https://github.com/ruozhi67/waterctl_electron/blob/main/src/writeValueLogging.ts"
click node_utils "https://github.com/ruozhi67/waterctl_electron/blob/main/src/utils.ts"
click node_pwa "https://github.com/ruozhi67/waterctl_electron/blob/main/src/pwaHelper.ts"

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_entry,node_session,node_user toneBlue
class node_payloads,node_solvers,node_algorithms,node_wasm toneAmber
class node_errors,node_countdown,node_logger,node_txlog,node_utils toneMint
class node_electron_main,node_preload,node_pwa toneRose
class node_device toneIndigo
```

## Components

### Renderer and session

- [UI bootstrap](https://github.com/ruozhi67/waterctl_electron/blob/main/src/index.ts): `src/index.ts`
- [Bluetooth session](https://github.com/ruozhi67/waterctl_electron/blob/main/src/bluetooth.ts): `src/bluetooth.ts`

### Device protocol

- [Protocol payloads](https://github.com/ruozhi67/waterctl_electron/blob/main/src/payloads.ts): `src/payloads.ts`
- [Authentication and commands](https://github.com/ruozhi67/waterctl_electron/blob/main/src/solvers.ts): `src/solvers.ts`
- [Checksums](https://github.com/ruozhi67/waterctl_electron/blob/main/src/algorithms.ts): `src/algorithms.ts`
- [Key routine](https://github.com/ruozhi67/waterctl_electron/blob/main/src/deputy.wat): `src/deputy.wat`

### Session support

- [Error handling](https://github.com/ruozhi67/waterctl_electron/blob/main/src/errors.ts): `src/errors.ts`
- [Session countdown](https://github.com/ruozhi67/waterctl_electron/blob/main/src/Countdown.ts): `src/Countdown.ts`
- [Debug log](https://github.com/ruozhi67/waterctl_electron/blob/main/src/logger.ts): `src/logger.ts`
- [Write logging](https://github.com/ruozhi67/waterctl_electron/blob/main/src/writeValueLogging.ts): `src/writeValueLogging.ts`
- [Byte utilities](https://github.com/ruozhi67/waterctl_electron/blob/main/src/utils.ts): `src/utils.ts`

### Electron and offline

- [Electron automation](https://github.com/ruozhi67/waterctl_electron/blob/main/electron/main.ts): `electron/main.ts`
- [Renderer bridge](https://github.com/ruozhi67/waterctl_electron/blob/main/electron/preload.ts): `electron/preload.ts`
- [PWA helpers](https://github.com/ruozhi67/waterctl_electron/blob/main/src/pwaHelper.ts): `src/pwaHelper.ts`

### Other components

- **User**
- **Water controller**

## Connections

- User → UI bootstrap: uses (evidence: `README.md`)
- UI bootstrap → Bluetooth session: registers click (evidence: `src/index.ts`)
- UI bootstrap → Write logging: loads (evidence: `src/index.ts`)
- UI bootstrap → Renderer bridge: calls bridge (evidence: `src/index.ts`)
- Bluetooth session → Water controller: connects and exchanges (evidence: `src/bluetooth.ts`)
- Bluetooth session → Protocol payloads: sends protocol messages (evidence: `src/bluetooth.ts`)
- Bluetooth session → Authentication and commands: builds responses (evidence: `src/bluetooth.ts`)
- Bluetooth session → Error handling: resolves failures (evidence: `src/bluetooth.ts`)
- Bluetooth session → Debug log: reads and clears logs (evidence: `src/bluetooth.ts`)
- Bluetooth session → Byte utilities: formats received bytes (evidence: `src/bluetooth.ts`)
- Bluetooth session → Session countdown: starts and stops (evidence: `src/bluetooth.ts`)
- Authentication and commands → Checksums: calculates checksums (evidence: `src/solvers.ts`)
- Authentication and commands → Byte utilities: converts values (evidence: `src/solvers.ts`)
- Authentication and commands → Key routine: uses key routine (evidence: `src/solvers.ts`)
- Write logging → Debug log: records writes (evidence: `src/writeValueLogging.ts`)
- Write logging → Byte utilities: formats writes (evidence: `src/writeValueLogging.ts`)
- Electron automation → Renderer bridge
- Electron automation → Bluetooth session: automates connection
- UI bootstrap → PWA helpers: optional PWA setup (evidence: `src/index.ts`)
