# aleszupanc/palazzetti-stove-hub architecture

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

- Interactive diagram: https://gitdiagram.com/aleszupanc/palazzetti-stove-hub
- Repository: https://github.com/aleszupanc/palazzetti-stove-hub

## Overview

Palazzetti Stove Hub controls a Connection Box locally, with a Raspberry Pi serving the home dashboard and running weekly schedules. For remote use, the browser and Pi establish end-to-end encrypted sessions through a VPS relay; the VPS also provides accounts and push delivery. The graph preserves the documented app, pairing, and notification capabilities. Some app and cloud internals are unsampled, so their connections are shown only where the README or indexed source references support them.

Main entry points: [`stove_master.py`](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stove_master.py) (Hub runtime), [`www/app/app.js`](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/app/app.js) (Stove app), [`stovemaster/cloud.py`](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/cloud.py) (Remote link), [`stovemaster/api.py`](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/api.py) (Hub RPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pi["Home Hub"]
  node_hub_runtime["Hub runtime<br/>[stove_master.py]"]
  node_hub_config["Hub configuration<br/>[config.py]"]
  node_hub_db[("Hub state store<br/>[db.py]")]
  node_lan["Local WebSocket<br/>[lan.py]"]
  node_rpc["Hub RPC<br/>[api.py]"]
  node_url_api["URL controls<br/>[urlapi.py]"]
  node_mdns["Local discovery<br/>[mdns.py]"]
  node_scheduler["Weekly scheduler<br/>[scheduler.py]"]
  node_cloud_link["Remote link<br/>[cloud.py]"]
  node_e2e["Encryption<br/>[e2e.py]"]
  node_webpush["Push encryption<br/>[webpush.py]"]
end

subgraph group_control["Stove Control"]
  node_stove_service["Stove service<br/>[stove.py]"]
  node_protocol["Box protocol<br/>[palazzetti.py]"]
end

subgraph group_cloud["Remote Service"]
  node_website["Website service<br/>[web.py]"]
  node_accounts["Accounts<br/>[accounts.py]"]
  node_relay["Encrypted relay<br/>[hub.py]"]
  node_cloud_ws["Cloud WebSockets<br/>[ws.py]"]
  node_cloud_db[("Cloud store<br/>[db.py]")]
  node_cloud_push["Push delivery<br/>[push.py]"]
end

subgraph group_app["Browser App"]
  node_browser_app["Stove app<br/>[app.js]"]
  node_browser_cloud["Remote app access<br/>[cloud.js]"]
  node_browser_local["Local app access<br/>[local.js]"]
  node_schedule_ui["Schedule screen<br/>[schedule.js]"]
  node_notifications_ui["Push client<br/>[push.js]"]
end

node_home_user(("Home user"))
node_remote_user(("Remote user"))
node_connection_box["Connection Box"]
node_stove["Pellet stove"]
node_push_service["Push service"]
node_email_service["Email service"]

node_home_user -->|"uses locally"| node_browser_app
node_remote_user -->|"uses remotely"| node_browser_app
node_browser_app -->|"opens local"| node_browser_local
node_browser_app -->|"opens remote"| node_browser_cloud
node_browser_local -->|"connects by WebSocket"| node_lan
node_lan -->|"dispatches RPC"| node_rpc
node_cloud_link -->|"dispatches RPC"| node_rpc
node_rpc -->|"handles schedule"| node_scheduler
node_rpc -->|"handles controls"| node_stove_service
node_scheduler -->|"commands stove"| node_stove_service
node_stove_service -->|"uses box client"| node_protocol
node_protocol -->|"sends HTTP"| node_connection_box
node_connection_box -->|"controls serial"| node_stove
node_hub_runtime -->|"loads config"| node_hub_config
node_hub_runtime -->|"initializes store"| node_hub_db
node_hub_runtime -->|"starts scheduler"| node_scheduler
node_hub_runtime -->|"starts hub API"| node_rpc
node_hub_runtime -->|"starts responder"| node_mdns
node_hub_runtime -->|"starts remote link"| node_cloud_link
node_mdns -->|"advertises local name"| node_home_user
node_cloud_link -->|"seals sessions"| node_e2e
node_cloud_link -->|"encrypts notices"| node_webpush
node_browser_cloud -->|"loads app and API"| node_website
node_browser_cloud -->|"encrypts messages"| node_e2e
node_website -->|"routes account requests"| node_accounts
node_website -->|"serves WebSockets"| node_cloud_ws
node_website -->|"routes hub sessions"| node_relay
node_relay -->|"handles socket sessions"| node_cloud_ws
node_relay -->|"updates device state"| node_cloud_db
node_cloud_link -->|"forwards ciphertext"| node_relay
node_browser_cloud -->|"forwards ciphertext"| node_relay
node_schedule_ui -.->|"renders schedule"| node_browser_app
node_notifications_ui -.->|"registers notifications"| node_browser_app
node_webpush -->|"sends ciphertext"| node_cloud_push
node_cloud_push -->|"delivers notification"| node_push_service
node_accounts -.->|"requests email"| node_email_service

click node_hub_runtime "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stove_master.py"
click node_hub_config "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/config.py"
click node_hub_db "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/db.py"
click node_lan "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/lan.py"
click node_rpc "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/api.py"
click node_url_api "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/urlapi.py"
click node_mdns "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/mdns.py"
click node_scheduler "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/scheduler.py"
click node_stove_service "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/stove.py"
click node_protocol "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/palazzetti.py"
click node_cloud_link "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/cloud.py"
click node_e2e "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/e2e.py"
click node_webpush "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/webpush.py"
click node_browser_app "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/app/app.js"
click node_browser_cloud "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/app/cloud.js"
click node_browser_local "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/app/local.js"
click node_schedule_ui "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/app/schedule.js"
click node_notifications_ui "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/app/push.js"
click node_website "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/stovecloud/web.py"
click node_accounts "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/stovecloud/accounts.py"
click node_relay "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/stovecloud/hub.py"
click node_cloud_ws "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/stovecloud/ws.py"
click node_cloud_db "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/stovecloud/db.py"
click node_cloud_push "https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/stovecloud/push.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_hub_runtime,node_hub_config,node_hub_db,node_lan,node_rpc,node_url_api,node_mdns,node_scheduler,node_cloud_link,node_e2e,node_webpush,node_home_user,node_remote_user toneBlue
class node_stove_service,node_protocol toneAmber
class node_website,node_accounts,node_relay,node_cloud_ws,node_cloud_db,node_cloud_push toneMint
class node_browser_app,node_browser_cloud,node_browser_local,node_schedule_ui,node_notifications_ui toneRose
class node_connection_box,node_stove,node_push_service,node_email_service toneIndigo
```

## Components

### Home Hub

- [Hub runtime](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stove_master.py): `stove_master.py`
- [Hub configuration](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/config.py): `stovemaster/config.py`
- [Hub state store](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/db.py): `stovemaster/db.py`
- [Local WebSocket](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/lan.py): `stovemaster/lan.py`
- [Hub RPC](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/api.py): `stovemaster/api.py`
- [URL controls](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/urlapi.py): `stovemaster/urlapi.py`
- [Local discovery](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/mdns.py): `stovemaster/mdns.py`
- [Weekly scheduler](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/scheduler.py): `stovemaster/scheduler.py`
- [Remote link](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/cloud.py): `stovemaster/cloud.py`
- [Encryption](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/e2e.py): `stovemaster/e2e.py`
- [Push encryption](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/webpush.py): `stovemaster/webpush.py`

### Stove Control

- [Stove service](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/stovemaster/stove.py): `stovemaster/stove.py`
- [Box protocol](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/palazzetti.py): `palazzetti.py`

### Remote Service

- [Website service](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/stovecloud/web.py): `www/stovecloud/web.py`
- [Accounts](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/stovecloud/accounts.py): `www/stovecloud/accounts.py`
- [Encrypted relay](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/stovecloud/hub.py): `www/stovecloud/hub.py`
- [Cloud WebSockets](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/stovecloud/ws.py): `www/stovecloud/ws.py`
- [Cloud store](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/stovecloud/db.py): `www/stovecloud/db.py`
- [Push delivery](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/stovecloud/push.py): `www/stovecloud/push.py`

### Browser App

- [Stove app](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/app/app.js): `www/app/app.js`
- [Remote app access](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/app/cloud.js): `www/app/cloud.js`
- [Local app access](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/app/local.js): `www/app/local.js`
- [Schedule screen](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/app/schedule.js): `www/app/schedule.js`
- [Push client](https://github.com/aleszupanc/palazzetti-stove-hub/blob/main/www/app/push.js): `www/app/push.js`

### Other components

- **Home user**
- **Remote user**
- **Connection Box**
- **Pellet stove**
- **Push service**
- **Email service**

## Connections

- Home user → Stove app: uses locally
- Remote user → Stove app: uses remotely
- Stove app → Local app access: opens local (evidence: `www/app/app.js`)
- Stove app → Remote app access: opens remote (evidence: `www/app/app.js`)
- Local app access → Local WebSocket: connects by WebSocket
- Local WebSocket → Hub RPC: dispatches RPC (evidence: `stovemaster/lan.py`)
- Remote link → Hub RPC: dispatches RPC (evidence: `stovemaster/cloud.py`)
- Hub RPC → Weekly scheduler: handles schedule (evidence: `stovemaster/api.py`)
- Hub RPC → Stove service: handles controls (evidence: `stovemaster/api.py`)
- Weekly scheduler → Stove service: commands stove (evidence: `stovemaster/scheduler.py`)
- Stove service → Box protocol: uses box client (evidence: `stovemaster/stove.py`)
- Box protocol → Connection Box: sends HTTP
- Connection Box → Pellet stove: controls serial
- Hub runtime → Hub configuration: loads config (evidence: `stove_master.py`)
- Hub runtime → Hub state store: initializes store (evidence: `stove_master.py`)
- Hub runtime → Weekly scheduler: starts scheduler (evidence: `stove_master.py`)
- Hub runtime → Hub RPC: starts hub API (evidence: `stove_master.py`)
- Hub runtime → Local discovery: starts responder (evidence: `stove_master.py`)
- Hub runtime → Remote link: starts remote link (evidence: `stove_master.py`)
- Local discovery → Home user: advertises local name
- Remote link → Encryption: seals sessions (evidence: `stovemaster/cloud.py`)
- Remote link → Push encryption: encrypts notices (evidence: `stovemaster/cloud.py`)
- Remote app access → Website service: loads app and API
- Remote app access → Encryption: encrypts messages
- Website service → Accounts: routes account requests (evidence: `www/stovecloud/web.py`)
- Website service → Cloud WebSockets: serves WebSockets (evidence: `www/stovecloud/web.py`)
- Website service → Encrypted relay: routes hub sessions (evidence: `www/stovecloud/web.py`)
- Encrypted relay → Cloud WebSockets: handles socket sessions (evidence: `www/stovecloud/hub.py`)
- Encrypted relay → Cloud store: updates device state (evidence: `www/stovecloud/hub.py`)
- Remote link → Encrypted relay: forwards ciphertext
- Remote app access → Encrypted relay: forwards ciphertext
- Schedule screen → Stove app: renders schedule
- Push client → Stove app: registers notifications
- Push encryption → Push delivery: sends ciphertext
- Push delivery → Push service: delivers notification
- Accounts → Email service: requests email