# mthek/brunata-fetcher-ha-addon architecture

> Architecture diagram of the GitHub repository mthek/brunata-fetcher-ha-addon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mthek/brunata-fetcher-ha-addon
- Repository: https://github.com/mthek/brunata-fetcher-ha-addon

## Overview

Brunata Fetcher is a Home Assistant add-on that periodically logs in to the Brunata München portal, collects configured consumption readings, validates query success, and publishes readings and status as MQTT Discovery entities. The server owns configuration, scheduling, MQTT setup, validation, and publication; the scraper handles portal interaction and extraction. README capabilities include three energy types, Supervisor MQTT discovery, query-health reporting, and failure notifications. Some server implementation is unsampled, so uncertain internal wiring is omitted.

Main entry points: [`brunata_fetcher/server.py`](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py) (Polling server), [`brunata_fetcher/_brunata_scraper.py`](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/_brunata_scraper.py) (Portal scraper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Add-on runtime"]
  node_server["Polling server<br/>[server.py]"]
  node_scheduler["Query schedule<br/>[server.py]"]
  node_validation["Result validation<br/>[server.py]"]
  node_mqtt_options["MQTT options<br/>[server.py]"]
end

subgraph group_portal["Portal acquisition"]
  node_scraper["Portal scraper"]
end

subgraph group_mqtt["MQTT entities"]
  node_mqtt_client["MQTT connection<br/>[server.py]"]
  node_mqtt_publish["Entity publication<br/>[server.py]"]
end

subgraph group_ha["Home Assistant integration"]
  node_supervisor["Supervisor MQTT discovery<br/>[server.py]"]
  node_discovery["Entity discovery<br/>[server.py]"]
  node_entity_states["Reading and status entities<br/>[server.py]"]
  node_notifications["Failure notification<br/>[server.py]"]
end

node_ha_options["Add-on options"]
node_portal_service(("Brunata portal"))
node_supervisor_service(("Supervisor services"))
node_broker[("MQTT broker")]
node_home_assistant(("Home Assistant"))

node_ha_options -->|"provides options"| node_server
node_server -->|"runs queries"| node_scheduler
node_scheduler -->|"requests scrape"| node_scraper
node_scraper -->|"logs in and reads"| node_portal_service
node_scraper -->|"returns readings"| node_server
node_server -->|"validates result"| node_validation
node_server -->|"resolves settings"| node_mqtt_options
node_mqtt_options -.->|"uses fallback"| node_supervisor
node_supervisor -.->|"queries MQTT service"| node_supervisor_service
node_mqtt_options -->|"configures connection"| node_mqtt_client
node_mqtt_client -->|"connects"| node_broker
node_server -->|"publishes configs"| node_discovery
node_server -->|"publishes readings and health"| node_entity_states
node_discovery -->|"sends discovery topics"| node_mqtt_publish
node_entity_states -->|"sends state topics"| node_mqtt_publish
node_mqtt_publish -->|"publishes retained messages"| node_broker
node_broker -->|"delivers MQTT entities"| node_home_assistant
node_server -->|"reports query failures"| node_notifications
node_notifications -->|"creates notification"| node_home_assistant

click node_server "https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py"
click node_scheduler "https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py"
click node_validation "https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py"
click node_scraper "https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/_brunata_scraper.py"
click node_mqtt_options "https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py"
click node_supervisor "https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py"
click node_mqtt_client "https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py"
click node_mqtt_publish "https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py"
click node_discovery "https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py"
click node_entity_states "https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py"
click node_notifications "https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.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_server,node_scheduler,node_validation,node_mqtt_options toneBlue
class node_scraper,node_broker toneAmber
class node_mqtt_client,node_mqtt_publish toneMint
class node_supervisor,node_discovery,node_entity_states,node_notifications toneRose
class node_ha_options,node_portal_service,node_supervisor_service,node_home_assistant toneIndigo
```

## Components

### Add-on runtime

- [Polling server](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py): `brunata_fetcher/server.py`
- [Query schedule](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py): `brunata_fetcher/server.py`
- [Result validation](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py): `brunata_fetcher/server.py`
- [MQTT options](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py): `brunata_fetcher/server.py`

### Portal acquisition

- [Portal scraper](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/_brunata_scraper.py): `brunata_fetcher/_brunata_scraper.py`

### MQTT entities

- [MQTT connection](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py): `brunata_fetcher/server.py`
- [Entity publication](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py): `brunata_fetcher/server.py`

### Home Assistant integration

- [Supervisor MQTT discovery](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py): `brunata_fetcher/server.py`
- [Entity discovery](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py): `brunata_fetcher/server.py`
- [Reading and status entities](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py): `brunata_fetcher/server.py`
- [Failure notification](https://github.com/mthek/brunata-fetcher-ha-addon/blob/main/brunata_fetcher/server.py): `brunata_fetcher/server.py`

### Other components

- **Add-on options**
- **Brunata portal**
- **Supervisor services**
- **MQTT broker**
- **Home Assistant**

## Connections

- Add-on options → Polling server: provides options
- Polling server → Query schedule: runs queries
- Query schedule → Portal scraper: requests scrape
- Portal scraper → Brunata portal: logs in and reads
- Portal scraper → Polling server: returns readings
- Polling server → Result validation: validates result
- Polling server → MQTT options: resolves settings
- MQTT options → Supervisor MQTT discovery: uses fallback
- Supervisor MQTT discovery → Supervisor services: queries MQTT service
- MQTT options → MQTT connection: configures connection
- MQTT connection → MQTT broker: connects
- Polling server → Entity discovery: publishes configs
- Polling server → Reading and status entities: publishes readings and health
- Entity discovery → Entity publication: sends discovery topics
- Reading and status entities → Entity publication: sends state topics
- Entity publication → MQTT broker: publishes retained messages
- MQTT broker → Home Assistant: delivers MQTT entities
- Polling server → Failure notification: reports query failures
- Failure notification → Home Assistant: creates notification