# lehel67/deer-outages architecture

> Architecture diagram of the GitHub repository lehel67/deer-outages, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lehel67/deer-outages
- Repository: https://github.com/lehel67/deer-outages

## Overview

DEER Outages is a Home Assistant integration that retrieves public planned-outage and incident feeds, filters them to configured counties, localities, and streets, then exposes address-specific sensors, binary sensors, calendar events, and new-outage events. The runtime path is configuration and feed retrieval through parsing/matching and the coordinator into entity platforms. The README documents freshness fallback and area-only warnings; source excerpts establish the principal calls. Calendar, diagnostics, and platform setup are retained as distinct capabilities, with no unsupported links inferred for unsampled wiring.

Main entry points: [`custom_components/deer_outages/coordinator.py`](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/coordinator.py) (Polling coordinator), [`custom_components/deer_outages/calendar.py`](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/calendar.py) (Outage calendar), [`custom_components/deer_outages/config_flow.py`](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/config_flow.py) (Address config), [`custom_components/deer_outages/api.py`](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/api.py) (DEER API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Address setup"]
  node_flow["Address config<br/>[config_flow.py]"]
  node_constants["Integration settings<br/>[const.py]"]
end

subgraph group_ingest["Feed ingestion"]
  node_api["DEER API client<br/>[api.py]"]
  node_feed["Shared feed cache<br/>[feed.py]"]
end

subgraph group_domain["Outage processing"]
  node_outages["Parse and match outages<br/>[outages.py]"]
  node_coordinator["Polling coordinator<br/>[coordinator.py]"]
  node_seen[("Seen-outage storage<br/>[coordinator.py]")]
  node_texts["Localized outage text<br/>[texts.py]"]
end

subgraph group_ha["Home Assistant outputs"]
  node_entity["Shared entity base<br/>[entity.py]"]
  node_sensors["Outage sensors<br/>[sensor.py]"]
  node_binary["Status sensors<br/>[binary_sensor.py]"]
  node_calendar["Outage calendar<br/>[calendar.py]"]
  node_diagnostics["Integration diagnostics<br/>[diagnostics.py]"]
end

node_user(("Home Assistant user"))
node_deer[("DEER public feed")]
node_haevents(("Home Assistant events"))

node_user -->|"configures address"| node_flow
node_flow -->|"validates county"| node_api
node_flow -->|"uses county map"| node_constants
node_coordinator -->|"uses polling settings"| node_constants
node_feed -->|"fetches both feeds"| node_api
node_api -->|"requests outage data"| node_deer
node_coordinator -->|"gets regional feed"| node_feed
node_coordinator -->|"parses and filters"| node_outages
node_coordinator -->|"loads and saves keys"| node_seen
node_coordinator -->|"formats event message"| node_texts
node_coordinator -->|"fires new-outage event"| node_haevents
node_sensors -->|"reads outage state"| node_coordinator
node_binary -->|"reads current matches"| node_coordinator
node_calendar -->|"reads calendar matches"| node_coordinator
node_calendar -->|"builds event text"| node_texts
node_sensors -->|"uses shared base"| node_entity
node_binary -->|"uses shared base"| node_entity
node_calendar -->|"uses shared base"| node_entity
node_diagnostics -->|"reads coordinator status"| node_coordinator
node_haevents -.->|"announces outage"| node_user

click node_flow "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/config_flow.py"
click node_constants "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/const.py"
click node_api "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/api.py"
click node_feed "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/feed.py"
click node_outages "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/outages.py"
click node_coordinator "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/coordinator.py"
click node_seen "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/coordinator.py"
click node_texts "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/texts.py"
click node_entity "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/entity.py"
click node_sensors "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/sensor.py"
click node_binary "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/binary_sensor.py"
click node_calendar "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/calendar.py"
click node_diagnostics "https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/diagnostics.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_flow,node_constants,node_user toneBlue
class node_api,node_feed,node_deer toneAmber
class node_outages,node_coordinator,node_seen,node_texts toneMint
class node_entity,node_sensors,node_binary,node_calendar,node_diagnostics toneRose
class node_haevents toneIndigo
```

## Components

### Address setup

- [Address config](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/config_flow.py): `custom_components/deer_outages/config_flow.py`
- [Integration settings](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/const.py): `custom_components/deer_outages/const.py`

### Feed ingestion

- [DEER API client](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/api.py): `custom_components/deer_outages/api.py`
- [Shared feed cache](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/feed.py): `custom_components/deer_outages/feed.py`

### Outage processing

- [Parse and match outages](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/outages.py): `custom_components/deer_outages/outages.py`
- [Polling coordinator](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/coordinator.py): `custom_components/deer_outages/coordinator.py`
- [Seen-outage storage](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/coordinator.py): `custom_components/deer_outages/coordinator.py`
- [Localized outage text](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/texts.py): `custom_components/deer_outages/texts.py`

### Home Assistant outputs

- [Shared entity base](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/entity.py): `custom_components/deer_outages/entity.py`
- [Outage sensors](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/sensor.py): `custom_components/deer_outages/sensor.py`
- [Status sensors](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/binary_sensor.py): `custom_components/deer_outages/binary_sensor.py`
- [Outage calendar](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/calendar.py): `custom_components/deer_outages/calendar.py`
- [Integration diagnostics](https://github.com/lehel67/deer-outages/blob/main/custom_components/deer_outages/diagnostics.py): `custom_components/deer_outages/diagnostics.py`

### Other components

- **Home Assistant user**
- **DEER public feed**
- **Home Assistant events**

## Connections

- Home Assistant user → Address config: configures address (evidence: `README.md`)
- Address config → DEER API client: validates county (evidence: `custom_components/deer_outages/config_flow.py`)
- Address config → Integration settings: uses county map (evidence: `custom_components/deer_outages/config_flow.py`)
- Polling coordinator → Integration settings: uses polling settings (evidence: `custom_components/deer_outages/coordinator.py`)
- Shared feed cache → DEER API client: fetches both feeds (evidence: `custom_components/deer_outages/feed.py`)
- DEER API client → DEER public feed: requests outage data (evidence: `custom_components/deer_outages/api.py`)
- Polling coordinator → Shared feed cache: gets regional feed (evidence: `custom_components/deer_outages/coordinator.py`)
- Polling coordinator → Parse and match outages: parses and filters (evidence: `custom_components/deer_outages/coordinator.py`)
- Polling coordinator → Seen-outage storage: loads and saves keys (evidence: `custom_components/deer_outages/coordinator.py`)
- Polling coordinator → Localized outage text: formats event message (evidence: `custom_components/deer_outages/coordinator.py`)
- Polling coordinator → Home Assistant events: fires new-outage event (evidence: `custom_components/deer_outages/coordinator.py`)
- Outage sensors → Polling coordinator: reads outage state (evidence: `custom_components/deer_outages/sensor.py`)
- Status sensors → Polling coordinator: reads current matches (evidence: `custom_components/deer_outages/binary_sensor.py`)
- Outage calendar → Polling coordinator: reads calendar matches (evidence: `custom_components/deer_outages/calendar.py`)
- Outage calendar → Localized outage text: builds event text (evidence: `custom_components/deer_outages/calendar.py`)
- Outage sensors → Shared entity base: uses shared base (evidence: `custom_components/deer_outages/sensor.py`)
- Status sensors → Shared entity base: uses shared base (evidence: `custom_components/deer_outages/binary_sensor.py`)
- Outage calendar → Shared entity base: uses shared base (evidence: `custom_components/deer_outages/calendar.py`)
- Integration diagnostics → Polling coordinator: reads coordinator status (evidence: `custom_components/deer_outages/diagnostics.py`)
- Home Assistant events → Home Assistant user: announces outage (evidence: `README.md`)