# krissen/pollenprognos-card architecture

> Architecture diagram of the GitHub repository krissen/pollenprognos-card, 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/krissen/pollenprognos-card
- Repository: https://github.com/krissen/pollenprognos-card

## Overview

##### Project type and purpose
- This is a frontend “Lovelace card” plugin for Home Assistant. Its sole responsibility is to render pollen forecast data (provided by the Home Assistant Pollenprognos integration) in the Lovelace UI. It does not contain any backend logic of its own.

##### File structure
- Top level:
- pollenprognos-card.js – the single JavaScript file exporting the custom card.
- README.md – documentation of the card’s configuration, features, and usage.
- hacs.json – metadata that lets HACS (Home Assistant Community Store) recognize and install the card.
- .github/workflows/hacs_action.yml – CI workflow to publish or validate the card via GitHub Actions.
- No “backend” or server‐side code here—this is purely a frontend integration.

##### README for additional insights
- The card reads data from sensor entities created by the Home Assistant Pollenprognos integration.
- Configuration options (city, allergens, days, text options, custom phrases) drive how data is displayed, but all data retrieval is handled by Home Assistant.
- The images and YAML samples show how the card is embedded in Lovelace dashboards.

a. Main components
- External Pollen Forecast API – the third‐party service that provides raw pollen data.
- Home Assistant Pollenprognos Integration (Python backend) – fetches from the external API on a schedule and exposes sensor entities.
- Home Assistant Core – hosts the integration, manages state machine and WebSocket/REST API.
- Sensor Entities (data layer) – each allergen/day combination is a stateful entity in Home Assistant.
- Lovelace UI – the user interface framework of Home Assistant.
- pollenprognos-card.js (Custom Card) – a frontend JavaScript component loaded into Lovelace to render charts/text.
- HACS (Home Assistant Community Store) – optional installation source for the card.
b. Relationships & data flow
1. Pollenprognos integration → polls External Pollen Forecast API → writes sensor states into Home Assistant Core
2. Lovelace UI loads pollenprognos-card.js (from local storage or HACS)
3. Custom Card opens WebSocket/REST connection to Home Assistant Core → subscribes to sensor entity state updates
4. Card processes state data and renders UI elements in the Lovelace dashboard
c. Architectural patterns & design principles
- Clear separation of concerns:
- Data ingestion & scheduling (integration/backend)
- Data storage & state management (Home Assistant Core)
- Presentation & user configuration (Lovelace Card JS)
- Plugin‐based architecture: card is a drop-in frontend plugin, integration is a drop-in backend plugin.
d. Relevant technologies & libraries
- Python (backend integration)
- Home Assistant Core (async engine, entity registry)
- JavaScript / Web Components (frontend Lovelace card)
- HACS metadata format (hacs.json)
- GitHub Actions (CI for validating and publishing)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    ExternalAPI["External Pollen Forecast API"]:::external

    %% Backend Integration Layer
    subgraph "Backend Integration"
        direction TB
        Integration["Pollenprognos Integration (Python)"]:::backend
    end

    %% Core Layer
    subgraph "Home Assistant Core"
        direction TB
        Core["Home Assistant Core"]:::core
        Sensors["Sensor Entities"]:::core
    end

    %% Frontend Layer
    subgraph "Lovelace UI"
        direction TB
        Card["pollenprognos-card.js\n(Custom Card)\nConfig inputs: city, allergens, days, phrases"]:::frontend
    end

    %% Distribution & CI
    subgraph "Distribution & CI"
        direction TB
        HACS["HACS Metadata\n(hacs.json)"]:::dist
        CI["GitHub Actions CI\n(.github/workflows/hacs_action.yml)"]:::ci
        Docs["Documentation\n(README.md)"]:::docs
    end

    %% Data Flow
    ExternalAPI -->|HTTP| Integration
    Integration -->|updates sensor states| Core
    Core -->|state machine| Sensors
    Sensors -->|WebSocket/REST| Card
    Card -->|renders UI| LovelaceUI[UI Dashboard]

    %% Distribution Flow
    CI -->|publishes| HACS
    Docs -->|explains| Card

    %% Click Events
    click Card "https://github.com/krissen/pollenprognos-card/blob/master/pollenprognos-card.js"
    click Docs "https://github.com/krissen/pollenprognos-card/blob/master/README.md"
    click HACS "https://github.com/krissen/pollenprognos-card/blob/master/hacs.json"
    click CI "https://github.com/krissen/pollenprognos-card/blob/master/.github/workflows/hacs_action.yml"

    %% Styles
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef backend fill:#a3d39c,stroke:#333,stroke-width:1px;
    classDef core fill:#9ec5fe,stroke:#333,stroke-width:1px;
    classDef frontend fill:#fdc27d,stroke:#333,stroke-width:1px;
    classDef dist fill:#e0e0e0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef ci fill:#f4cccc,stroke:#333,stroke-width:1px;
    classDef docs fill:#fff2cc,stroke:#333,stroke-width:1px;
```
