# joshwarren/truely-smart-home architecture

> Architecture diagram of the GitHub repository joshwarren/truely-smart-home, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joshwarren/truely-smart-home
- Repository: https://github.com/joshwarren/truely-smart-home

## Overview

This repository is a scheduled home-energy data collection and control proof of concept. Its principal workflow is a scheduler invoking weather, electricity-supplier, and solar-generation collectors that persist readings; tariff jobs also store tariff data and queue immersion-switch actions, while a separate scheduled action processor executes due commands. The README describes additional planned home systems and future optimization, but the supplied source does not show their implementations. The graph focuses on evidenced runtime behavior; the README documents the broader goals, and the source excerpts do not establish every external integration detail.

Main entry points: [`db.py`](https://github.com/joshwarren/truely-smart-home/blob/master/db.py) (SQL database), [`octopus_tariff_app.py`](https://github.com/joshwarren/truely-smart-home/blob/master/octopus_tariff_app.py) (Tariff services), [`dataCollector.py`](https://github.com/joshwarren/truely-smart-home/blob/master/dataCollector.py) (Job scheduler), [`config.py`](https://github.com/joshwarren/truely-smart-home/blob/master/config.py) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Scheduling"]
  node_scheduler["Job scheduler<br/>[dataCollector.py]"]
end

subgraph group_collection["Data collection"]
  node_weather["Weather collector<br/>[openWeather.py]"]
  node_supplier["Supplier collector<br/>[supply.py]"]
  node_solar["Solar collector<br/>[microGeneration.py]"]
end

subgraph group_control["Tariffs and control"]
  node_tariff["Tariff services"]
  node_action_queue["Action queue<br/>[action.py]"]
  node_device_dispatch["Device dispatch<br/>[action.py]"]
  node_sonoff["Sonoff switch"]
  node_shelly["Shelly switch"]
end

subgraph group_platform["Shared platform"]
  node_database[("SQL database<br/>[db.py]")]
  node_configuration["Configuration<br/>[config.py]"]
  node_logging["Logging<br/>[logger.py]"]
end

node_weather_api(("OpenWeather API"))
node_octopus_api(("Octopus API"))
node_solax_api(("Solax Cloud API"))
node_pushover(("Pushover"))

node_scheduler -->|"schedules"| node_weather
node_scheduler -->|"schedules"| node_supplier
node_scheduler -->|"schedules"| node_solar
node_scheduler -->|"schedules"| node_tariff
node_scheduler -->|"runs"| node_action_queue
node_weather -->|"requests forecast"| node_weather_api
node_weather -->|"writes forecast"| node_database
node_supplier -->|"uses tariff methods"| node_tariff
node_supplier -->|"writes readings"| node_database
node_tariff -->|"requests tariffs"| node_octopus_api
node_tariff -->|"queues actions"| node_database
node_tariff -->|"sends updates"| node_pushover
node_solar -->|"requests readings"| node_solax_api
node_solar -->|"writes readings"| node_database
node_action_queue -->|"reads and updates"| node_database
node_action_queue -->|"dispatches commands"| node_device_dispatch
node_device_dispatch -->|"controls device"| node_sonoff
node_device_dispatch -->|"controls device"| node_shelly
node_sonoff -.-> node_database
node_weather -->|"imports settings"| node_configuration
node_supplier -->|"imports settings"| node_configuration
node_solar -->|"imports settings"| node_configuration
node_tariff -->|"imports settings"| node_configuration
node_action_queue -->|"imports settings"| node_configuration
node_database -.-> node_logging

click node_scheduler "https://github.com/joshwarren/truely-smart-home/blob/master/dataCollector.py"
click node_weather "https://github.com/joshwarren/truely-smart-home/blob/master/openWeather.py"
click node_supplier "https://github.com/joshwarren/truely-smart-home/blob/master/supply.py"
click node_solar "https://github.com/joshwarren/truely-smart-home/blob/master/microGeneration.py"
click node_tariff "https://github.com/joshwarren/truely-smart-home/blob/master/octopus_tariff_app.py"
click node_action_queue "https://github.com/joshwarren/truely-smart-home/blob/master/action.py"
click node_device_dispatch "https://github.com/joshwarren/truely-smart-home/blob/master/action.py"
click node_database "https://github.com/joshwarren/truely-smart-home/blob/master/db.py"
click node_configuration "https://github.com/joshwarren/truely-smart-home/blob/master/config.py"
click node_logging "https://github.com/joshwarren/truely-smart-home/blob/master/logger.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_scheduler toneBlue
class node_weather,node_supplier,node_solar toneAmber
class node_tariff,node_action_queue,node_device_dispatch,node_sonoff,node_shelly,node_weather_api,node_octopus_api,node_solax_api toneMint
class node_database,node_configuration,node_logging toneRose
class node_pushover toneIndigo
```

## Components

### Scheduling

- [Job scheduler](https://github.com/joshwarren/truely-smart-home/blob/master/dataCollector.py): `dataCollector.py`

### Data collection

- [Weather collector](https://github.com/joshwarren/truely-smart-home/blob/master/openWeather.py): `openWeather.py`
- [Supplier collector](https://github.com/joshwarren/truely-smart-home/blob/master/supply.py): `supply.py`
- [Solar collector](https://github.com/joshwarren/truely-smart-home/blob/master/microGeneration.py): `microGeneration.py`

### Tariffs and control

- [Tariff services](https://github.com/joshwarren/truely-smart-home/blob/master/octopus_tariff_app.py): `octopus_tariff_app.py`
- [Action queue](https://github.com/joshwarren/truely-smart-home/blob/master/action.py): `action.py`
- [Device dispatch](https://github.com/joshwarren/truely-smart-home/blob/master/action.py): `action.py`
- **Sonoff switch**
- **Shelly switch**

### Shared platform

- [SQL database](https://github.com/joshwarren/truely-smart-home/blob/master/db.py): `db.py`
- [Configuration](https://github.com/joshwarren/truely-smart-home/blob/master/config.py): `config.py`
- [Logging](https://github.com/joshwarren/truely-smart-home/blob/master/logger.py): `logger.py`

### Other components

- **OpenWeather API**
- **Octopus API**
- **Solax Cloud API**
- **Pushover**

## Connections

- Job scheduler → Weather collector: schedules (evidence: `dataCollector.py`)
- Job scheduler → Supplier collector: schedules (evidence: `dataCollector.py`)
- Job scheduler → Solar collector: schedules (evidence: `dataCollector.py`)
- Job scheduler → Tariff services: schedules (evidence: `dataCollector.py`)
- Job scheduler → Action queue: runs (evidence: `dataCollector.py`)
- Weather collector → OpenWeather API: requests forecast (evidence: `openWeather.py`)
- Weather collector → SQL database: writes forecast (evidence: `openWeather.py`)
- Supplier collector → Tariff services: uses tariff methods (evidence: `supply.py`)
- Supplier collector → SQL database: writes readings (evidence: `supply.py`)
- Tariff services → Octopus API: requests tariffs (evidence: `octopus_tariff_app.py`)
- Tariff services → SQL database: queues actions (evidence: `octopus_tariff_app.py`)
- Tariff services → Pushover: sends updates (evidence: `octopus_tariff_app.py`)
- Solar collector → Solax Cloud API: requests readings (evidence: `microGeneration.py`)
- Solar collector → SQL database: writes readings (evidence: `microGeneration.py`)
- Action queue → SQL database: reads and updates (evidence: `action.py`)
- Action queue → Device dispatch: dispatches commands (evidence: `action.py`)
- Device dispatch → Sonoff switch: controls device (evidence: `action.py`)
- Device dispatch → Shelly switch: controls device (evidence: `action.py`)
- Sonoff switch → SQL database
- Weather collector → Configuration: imports settings (evidence: `openWeather.py`)
- Supplier collector → Configuration: imports settings (evidence: `supply.py`)
- Solar collector → Configuration: imports settings (evidence: `microGeneration.py`)
- Tariff services → Configuration: imports settings (evidence: `octopus_tariff_app.py`)
- Action queue → Configuration: imports settings (evidence: `action.py`)
- SQL database → Logging (evidence: `db.py`)