# hermannbjorgvin/clawdmeter architecture

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

- Interactive diagram: https://gitdiagram.com/hermannbjorgvin/clawdmeter
- Repository: https://github.com/hermannbjorgvin/clawdmeter

## Overview

Clawdmeter pairs an ESP32 usage dashboard with a host daemon: the daemon reads Claude credentials, polls usage, and sends updates over BLE; firmware renders usage and animations on the device. Windows adds a system-tray interface and login autostart. The firmware supports multiple Waveshare boards through a shared HAL. Several firmware subsystems are represented at their documented directory or module level because their implementation excerpts were not provided; uncertain connections are omitted or dashed.

Main entry points: [`firmware/src/main.cpp`](https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/main.cpp) (Firmware Loop), [`daemon/claude_usage_daemon_windows.py`](https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/claude_usage_daemon_windows.py) (Windows Daemon), [`daemon/claude_usage_daemon.py`](https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/claude_usage_daemon.py) (Host Daemon), [`daemon/tray_windows.py`](https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/tray_windows.py) (Tray App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host Monitoring"]
  node_linux_daemon["Host Daemon"]
  node_windows_daemon["Windows Daemon"]
end

subgraph group_tray["Windows Tray"]
  node_tray_app["Tray App<br/>[tray_windows.py]"]
  node_tray_state["Tray Status<br/>[tray_windows.py]"]
  node_tray_icons["Status Icons<br/>[icon_assets.py]"]
  node_autostart["Login Autostart"]
end

subgraph group_firmware["Device Experience"]
  node_firmware_main["Firmware Loop<br/>[main.cpp]"]
  node_usage_data["Usage Payload<br/>[data.h]"]
  node_usage_rate["Usage Rate<br/>[usage_rate.cpp]"]
  node_ui["Usage UI<br/>[ui.cpp]"]
  node_splash["Animated Splash<br/>[splash.cpp]"]
  node_idle_brightness["Idle Brightness<br/>[idle.cpp]"]
  node_brightness["Brightness Control<br/>[brightness.cpp]"]
  node_ble_firmware["BLE Transport<br/>[ble.h]"]
end

subgraph group_hardware["Board Hardware"]
  node_hal["Hardware HAL"]
  node_board_ports["Board Ports"]
end

node_user(("Device Owner"))
node_credentials[("Claude Credentials")]
node_anthropic["Claude Usage API"]
node_ble_device["BLE Dashboard"]

node_user -->|"provides"| node_credentials
node_linux_daemon -->|"reads"| node_credentials
node_windows_daemon -->|"reads"| node_credentials
node_linux_daemon -->|"polls usage"| node_anthropic
node_windows_daemon -->|"polls usage"| node_anthropic
node_linux_daemon -->|"sends updates"| node_ble_device
node_windows_daemon -->|"sends updates"| node_ble_device
node_windows_daemon -->|"updates status"| node_tray_state
node_tray_app -->|"runs loop"| node_windows_daemon
node_tray_app -->|"builds icons"| node_tray_icons
node_tray_app -->|"manages startup"| node_autostart
node_ble_device -->|"delivers payload"| node_firmware_main
node_firmware_main -->|"parses payload"| node_usage_data
node_firmware_main -->|"updates display"| node_ui
node_firmware_main -->|"initializes BLE"| node_ble_firmware
node_firmware_main -.->|"tracks rate"| node_usage_rate
node_firmware_main -.->|"drives animations"| node_splash
node_firmware_main -->|"initializes idle"| node_idle_brightness
node_idle_brightness -.->|"uses setting"| node_brightness
node_firmware_main -->|"uses interfaces"| node_hal
node_board_ports -->|"implements interfaces"| node_hal

click node_linux_daemon "https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/claude_usage_daemon.py"
click node_windows_daemon "https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/claude_usage_daemon_windows.py"
click node_tray_app "https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/tray_windows.py"
click node_tray_state "https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/tray_windows.py"
click node_tray_icons "https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/icon_assets.py"
click node_autostart "https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/autostart_windows.py"
click node_firmware_main "https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/main.cpp"
click node_usage_data "https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/data.h"
click node_usage_rate "https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/usage_rate.cpp"
click node_ui "https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/ui.cpp"
click node_splash "https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/splash.cpp"
click node_idle_brightness "https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/idle.cpp"
click node_brightness "https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/brightness.cpp"
click node_ble_firmware "https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/ble.h"
click node_hal "https://github.com/hermannbjorgvin/clawdmeter/tree/main/firmware/src/hal"
click node_board_ports "https://github.com/hermannbjorgvin/clawdmeter/tree/main/firmware/src/boards"

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_linux_daemon,node_windows_daemon toneBlue
class node_tray_app,node_tray_state,node_tray_icons,node_autostart,node_credentials toneAmber
class node_firmware_main,node_usage_data,node_usage_rate,node_ui,node_splash,node_idle_brightness,node_brightness,node_ble_firmware,node_anthropic toneMint
class node_hal,node_board_ports toneRose
class node_user,node_ble_device toneIndigo
```

## Components

### Host Monitoring

- [Host Daemon](https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/claude_usage_daemon.py): `daemon/claude_usage_daemon.py`
- [Windows Daemon](https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/claude_usage_daemon_windows.py): `daemon/claude_usage_daemon_windows.py`

### Windows Tray

- [Tray App](https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/tray_windows.py): `daemon/tray_windows.py`
- [Tray Status](https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/tray_windows.py): `daemon/tray_windows.py`
- [Status Icons](https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/icon_assets.py): `daemon/icon_assets.py`
- [Login Autostart](https://github.com/hermannbjorgvin/clawdmeter/blob/main/daemon/autostart_windows.py): `daemon/autostart_windows.py`

### Device Experience

- [Firmware Loop](https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`
- [Usage Payload](https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/data.h): `firmware/src/data.h`
- [Usage Rate](https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/usage_rate.cpp): `firmware/src/usage_rate.cpp`
- [Usage UI](https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/ui.cpp): `firmware/src/ui.cpp`
- [Animated Splash](https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/splash.cpp): `firmware/src/splash.cpp`
- [Idle Brightness](https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/idle.cpp): `firmware/src/idle.cpp`
- [Brightness Control](https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/brightness.cpp): `firmware/src/brightness.cpp`
- [BLE Transport](https://github.com/hermannbjorgvin/clawdmeter/blob/main/firmware/src/ble.h): `firmware/src/ble.h`

### Board Hardware

- [Hardware HAL](https://github.com/hermannbjorgvin/clawdmeter/tree/main/firmware/src/hal): `firmware/src/hal`
- [Board Ports](https://github.com/hermannbjorgvin/clawdmeter/tree/main/firmware/src/boards): `firmware/src/boards`

### Other components

- **Device Owner**
- **Claude Credentials**
- **Claude Usage API**
- **BLE Dashboard**

## Connections

- Device Owner → Claude Credentials: provides
- Host Daemon → Claude Credentials: reads
- Windows Daemon → Claude Credentials: reads
- Host Daemon → Claude Usage API: polls usage
- Windows Daemon → Claude Usage API: polls usage (evidence: `daemon/claude_usage_daemon_windows.py`)
- Host Daemon → BLE Dashboard: sends updates
- Windows Daemon → BLE Dashboard: sends updates
- Windows Daemon → Tray Status: updates status (evidence: `daemon/tray_windows.py`)
- Tray App → Windows Daemon: runs loop (evidence: `daemon/tray_windows.py`)
- Tray App → Status Icons: builds icons (evidence: `daemon/tray_windows.py`)
- Tray App → Login Autostart: manages startup (evidence: `daemon/tray_windows.py`)
- BLE Dashboard → Firmware Loop: delivers payload
- Firmware Loop → Usage Payload: parses payload (evidence: `firmware/src/main.cpp`)
- Firmware Loop → Usage UI: updates display (evidence: `firmware/src/main.cpp`)
- Firmware Loop → BLE Transport: initializes BLE (evidence: `firmware/src/main.cpp`)
- Firmware Loop → Usage Rate: tracks rate
- Firmware Loop → Animated Splash: drives animations
- Firmware Loop → Idle Brightness: initializes idle (evidence: `firmware/src/main.cpp`)
- Idle Brightness → Brightness Control: uses setting
- Firmware Loop → Hardware HAL: uses interfaces (evidence: `firmware/src/main.cpp`)
- Board Ports → Hardware HAL: implements interfaces (evidence: `firmware/src/boards/waveshare_amoled_216_c6/display.cpp`)
