# salihinsaealal/home-assistant-tnb-calculator architecture

> Architecture diagram of the GitHub repository salihinsaealal/home-assistant-tnb-calculator, 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/salihinsaealal/home-assistant-tnb-calculator
- Repository: https://github.com/salihinsaealal/home-assistant-tnb-calculator

## Overview

TNB Calculator is a Home Assistant integration for estimating Malaysian electricity bills from household energy sensors. Users configure import/export entities and tariff options; the integration tracks usage, applies ToU or non-ToU billing and AFA/NEM adjustments, then exposes costs, history, optimization, and diagnostics as Home Assistant entities. A companion scraper serves AFA and tariff data. The excerpts show coordinator ownership, spike handling, and API routes, but not the full calculation or storage implementation; those links are limited accordingly.

Main entry points: [`custom_components/tnb_calculator/sensor.py`](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/sensor.py) (Usage coordinator), [`custom_components/tnb_calculator/__init__.py`](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/__init__.py) (Integration lifecycle and services), [`custom_components/tnb_calculator/config_flow.py`](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/config_flow.py) (Integration setup), [`tnb-afa-scraper/main.py`](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/tnb-afa-scraper/main.py) (AFA and tariff API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and Control"]
  node_config["Integration setup<br/>[config_flow.py]"]
  node_integration["Integration lifecycle and services<br/>[__init__.py]"]
end

subgraph group_billing["Usage and Billing"]
  node_coordinator["Usage coordinator<br/>[sensor.py]"]
  node_calculation["Billing and optimization<br/>[sensor.py]"]
  node_state[("Persisted usage and tariff state<br/>[sensor.py]")]
end

subgraph group_entities["Home Assistant Entities"]
  node_controls["Tariff and spike controls<br/>[button.py]"]
  node_switch["Auto-fetch switch<br/>[switch.py]"]
  node_url["AFA URL setting<br/>[text.py]"]
  node_entities_sensor["Billing and diagnostic sensors<br/>[sensor.py]"]
  node_dashboard["Dashboard"]
  node_automation["AFA update automation"]
end

subgraph group_rates["Rate Service"]
  node_scraper["AFA and tariff API<br/>[main.py]"]
end

node_user(("Home Assistant user"))
node_energy(("Energy sensors"))
node_ha(("Home Assistant"))
node_tnb(("TNB rate source"))

node_user -->|"configures"| node_config
node_config -->|"creates entry"| node_integration
node_integration -->|"initializes"| node_coordinator
node_integration -->|"forwards platforms"| node_entities_sensor
node_energy -.->|"provides readings"| node_coordinator
node_coordinator -.->|"calculates bills"| node_calculation
node_coordinator -.->|"persists data"| node_state
node_calculation -.->|"supplies sensor values"| node_entities_sensor
node_integration -->|"dispatches services"| node_coordinator
node_controls -->|"accepts spike"| node_coordinator
node_switch -->|"toggles fetching"| node_coordinator
node_url -->|"saves URL"| node_state
node_coordinator -->|"fetches tariffs"| node_scraper
node_scraper -->|"scrapes rates"| node_tnb
node_dashboard -.->|"presents entities"| node_entities_sensor
node_automation -.->|"updates AFA"| node_integration

click node_config "https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/config_flow.py"
click node_integration "https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/__init__.py"
click node_controls "https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/button.py"
click node_switch "https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/switch.py"
click node_url "https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/text.py"
click node_coordinator "https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/sensor.py"
click node_calculation "https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/sensor.py"
click node_state "https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/sensor.py"
click node_entities_sensor "https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/sensor.py"
click node_dashboard "https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/dashboards/tnb_calculator_dashboard.yaml"
click node_automation "https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/blueprints/automation/tnb_calculator/auto_update_afa_rate.yaml"
click node_scraper "https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/tnb-afa-scraper/main.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_config,node_integration,node_user toneBlue
class node_coordinator,node_calculation,node_state toneAmber
class node_controls,node_switch,node_url,node_entities_sensor,node_dashboard,node_automation toneMint
class node_scraper toneRose
class node_energy,node_ha,node_tnb toneIndigo
```

## Components

### Setup and Control

- [Integration setup](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/config_flow.py): `custom_components/tnb_calculator/config_flow.py`
- [Integration lifecycle and services](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/__init__.py): `custom_components/tnb_calculator/__init__.py`

### Usage and Billing

- [Usage coordinator](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/sensor.py): `custom_components/tnb_calculator/sensor.py`
- [Billing and optimization](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/sensor.py): `custom_components/tnb_calculator/sensor.py`
- [Persisted usage and tariff state](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/sensor.py): `custom_components/tnb_calculator/sensor.py`

### Home Assistant Entities

- [Tariff and spike controls](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/button.py): `custom_components/tnb_calculator/button.py`
- [Auto-fetch switch](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/switch.py): `custom_components/tnb_calculator/switch.py`
- [AFA URL setting](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/text.py): `custom_components/tnb_calculator/text.py`
- [Billing and diagnostic sensors](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/custom_components/tnb_calculator/sensor.py): `custom_components/tnb_calculator/sensor.py`
- [Dashboard](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/dashboards/tnb_calculator_dashboard.yaml): `dashboards/tnb_calculator_dashboard.yaml`
- [AFA update automation](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/blueprints/automation/tnb_calculator/auto_update_afa_rate.yaml): `blueprints/automation/tnb_calculator/auto_update_afa_rate.yaml`

### Rate Service

- [AFA and tariff API](https://github.com/salihinsaealal/home-assistant-tnb-calculator/blob/master/tnb-afa-scraper/main.py): `tnb-afa-scraper/main.py`

### Other components

- **Home Assistant user**
- **Energy sensors**
- **Home Assistant**
- **TNB rate source**

## Connections

- Home Assistant user → Integration setup: configures (evidence: `custom_components/tnb_calculator/config_flow.py`)
- Integration setup → Integration lifecycle and services: creates entry (evidence: `custom_components/tnb_calculator/config_flow.py`)
- Integration lifecycle and services → Usage coordinator: initializes (evidence: `custom_components/tnb_calculator/__init__.py`)
- Integration lifecycle and services → Billing and diagnostic sensors: forwards platforms (evidence: `custom_components/tnb_calculator/__init__.py`)
- Energy sensors → Usage coordinator: provides readings
- Usage coordinator → Billing and optimization: calculates bills (evidence: `custom_components/tnb_calculator/sensor.py`)
- Usage coordinator → Persisted usage and tariff state: persists data (evidence: `custom_components/tnb_calculator/sensor.py`)
- Billing and optimization → Billing and diagnostic sensors: supplies sensor values (evidence: `custom_components/tnb_calculator/sensor.py`)
- Integration lifecycle and services → Usage coordinator: dispatches services (evidence: `custom_components/tnb_calculator/__init__.py`)
- Tariff and spike controls → Usage coordinator: accepts spike (evidence: `custom_components/tnb_calculator/button.py`)
- Auto-fetch switch → Usage coordinator: toggles fetching (evidence: `custom_components/tnb_calculator/switch.py`)
- AFA URL setting → Persisted usage and tariff state: saves URL (evidence: `custom_components/tnb_calculator/text.py`)
- Usage coordinator → AFA and tariff API: fetches tariffs (evidence: `custom_components/tnb_calculator/sensor.py`)
- AFA and tariff API → TNB rate source: scrapes rates (evidence: `tnb-afa-scraper/main.py`)
- Dashboard → Billing and diagnostic sensors: presents entities (evidence: `README.md`)
- AFA update automation → Integration lifecycle and services: updates AFA (evidence: `README.md`)
