# johnan/homeassistant-pollenprognos architecture

> Architecture diagram of the GitHub repository johnan/homeassistant-pollenprognos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/johnan/homeassistant-pollenprognos
- Repository: https://github.com/johnan/homeassistant-pollenprognos

## Overview

##### Project type and purpose
- This is a Home Assistant custom integration (“Home Assistant Pollenprognos”) that pulls pollen forecasts for locations in Sweden from the external Pollenrapporten.se API, exposes them as Home Assistant sensor entities, and makes them available to the Home Assistant frontend (including Lovelace cards).

##### File structure
- Top-level support files & CI/CD:
- .github/workflows/*.yaml – CI for lint, validate, releases
- scripts/ – helper scripts (lint, setup, develop)
- manage/update_manifest.py – updates integration manifest version
- requirements.txt – development dependencies
- custom_components/pollenprognos/ – main integration code:
- manifest.json – integration metadata (domain, requirements)
- config_flow.py – UI-guided setup/credential flow in HA frontend
- api.py – lightweight wrapper over Pollenrapporten.se HTTP endpoints
- const.py – fixed constants (attribute keys, default values)
- entity.py – base class for Home Assistant entities (common logic)
- sensor.py – defines individual SensorEntity subclasses (pollen types, levels)
- translations/ & strings.json – localization support

##### README for additional insights
- Describes installation via HACS and Home Assistant UI

##### Main components and interactions
a. Components
- Home Assistant Core (event loop, entity registry, state machine)
- Pollenprognos Integration (the custom component)
– Config Flow submodule (UI setup)
– API Client submodule (api.py)
– Entity Model submodule (entity.py + sensor.py)
– Localization files (strings.json + translations folder)
- External Pollenrapporten.se REST API (HTTP service)
- Home Assistant Frontend (Lovelace dashboard displaying sensor cards)
- HACS (optional external installation source)
b. Relationships & data flows
1. User installs integration via HACS → integration files are placed under custom_components/
2. Home Assistant Core triggers config_flow → user enters location/credentials
3. Config_flow calls API client to validate config/user input
4. Scheduled polling: Integration’s API client issues HTTP GET to Pollenrapporten.se → returns JSON pollen data
5. Integration parses JSON → instantiates/updates SensorEntity objects → pushes new state into Home Assistant Core
6. Home Assistant Frontend queries Core for sensor states → renders Lovelace cards
c. Architectural patterns & principles
- Single-responsibility modules (API wrapper vs. entity definitions vs. config flow)
- Event-driven update loop via Home Assistant’s coordinator pattern (implicit in sensor.py)
- Localizable strings separated in JSON + translations (i18n)
- Manifest-driven dependency injection (manifest.json)
d. Key technologies & frameworks
- Python 3.x, Home Assistant Core integration API
- aiohttp or requests (indirect via Home Assistant HTTP helper)
- JSON translation files for i18n
- HACS for custom distribution

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Installation and Development
    HACS["HACS"]:::external
    CI["CI/CD Pipelines"]:::infra
    MUPDATE["Manifest Update Script"]:::infra
    REQ["requirements.txt"]:::infra
    SCRIPTS["Development Scripts"]:::infra

    %% Home Assistant Core
    subgraph "Home Assistant Core"
        CORE["Core (Event Loop, Entity Registry, State Machine)"]:::core
    end

    %% Custom Integration
    subgraph "Pollenprognos Integration" 
        MF["manifest.json"]:::integration
        CF["config_flow.py"]:::integration
        API["api.py"]:::integration
        ENT["entity.py"]:::integration
        SENS["sensor.py"]:::integration
        CONST["const.py"]:::integration
        STR["strings.json"]:::integration
        TRANS["translations/"]:::integration
    end

    %% External Service and Frontend
    External["External REST API\n(Pollenrapporten.se)"]:::external
    Frontend["HA Frontend\n(Lovelace UI)"]:::frontend

    %% Data Flows and Relationships
    HACS -->|"Installs Integration"| MF
    CI -->|"Runs lint/validate/releases"| MF
    MUPDATE -->|"Updates version in"| MF
    REQ -->|"Dev dependencies for"| MF
    SCRIPTS -->|"Helper scripts for"| MF

    CORE -->|"Triggers setup flow"| CF
    CF -->|"Validate config via"| API
    CORE -->|"Scheduled polling triggers"| API
    API -->|"HTTP GET request"| External
    External -->|"JSON response"| API
    API -->|"Parse data and notify"| SENS
    SENS -->|"Use base logic in"| ENT
    ENT -->|"Push updated state to"| CORE
    CORE -->|"Expose state to"| Frontend
    Frontend -->|"Query states from"| CORE

    ENT -->|"Uses constants from"| CONST
    SENS -->|"Uses constants from"| CONST
    ENT -->|"Localization strings from"| STR
    ENT -->|"Translations from"| TRANS
    SENS -->|"Localization strings from"| STR

    %% Click Events
    click MF "https://github.com/johnan/homeassistant-pollenprognos/blob/master/custom_components/pollenprognos/manifest.json"
    click CF "https://github.com/johnan/homeassistant-pollenprognos/blob/master/custom_components/pollenprognos/config_flow.py"
    click API "https://github.com/johnan/homeassistant-pollenprognos/blob/master/custom_components/pollenprognos/api.py"
    click ENT "https://github.com/johnan/homeassistant-pollenprognos/blob/master/custom_components/pollenprognos/entity.py"
    click SENS "https://github.com/johnan/homeassistant-pollenprognos/blob/master/custom_components/pollenprognos/sensor.py"
    click CONST "https://github.com/johnan/homeassistant-pollenprognos/blob/master/custom_components/pollenprognos/const.py"
    click STR "https://github.com/johnan/homeassistant-pollenprognos/blob/master/custom_components/pollenprognos/strings.json"
    click TRANS "https://github.com/johnan/homeassistant-pollenprognos/tree/master/custom_components/pollenprognos/translations/"
    click CI "https://github.com/johnan/homeassistant-pollenprognos/tree/master/.github/workflows/"
    click MUPDATE "https://github.com/johnan/homeassistant-pollenprognos/blob/master/manage/update_manifest.py"
    click REQ "https://github.com/johnan/homeassistant-pollenprognos/blob/master/requirements.txt"
    click SCRIPTS "https://github.com/johnan/homeassistant-pollenprognos/tree/master/scripts/"

    %% Styles
    classDef core fill:#FFE599,stroke:#000
    classDef integration fill:#D5A6BD,stroke:#000
    classDef external fill:#93C47D,stroke:#000
    classDef frontend fill:#76A5AF,stroke:#000
    classDef infra fill:#F4CCCC,stroke:#000
```
