# lucasraamaa/climaalert architecture

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

- Interactive diagram: https://gitdiagram.com/lucasraamaa/climaalert
- Repository: https://github.com/lucasraamaa/climaalert

## Overview

ClimaAlert monitors weather at fixed locations, evaluates conditions, stores measurements and alert events, and optionally notifies via Telegram. Its React dashboard reads stored data and offers location search and 24-hour forecasts. The backend calls and data transfers shown are supported by the excerpts; dashboard capabilities and component relationships are also documented or referenced in the source index. Unsampled implementation details are omitted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/App.jsx) (Dashboard state), [`backend/main.py`](https://github.com/lucasraamaa/climaalert/blob/main/backend/main.py) (Monitoring cycle), [`backend/fetcher.py`](https://github.com/lucasraamaa/climaalert/blob/main/backend/fetcher.py) (Weather fetcher), [`backend/db.py`](https://github.com/lucasraamaa/climaalert/blob/main/backend/db.py) (Backend persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_monitoring["Weather monitoring"]
  node_worker["Monitoring cycle<br/>[main.py]"]
  node_config["Runtime config<br/>[config.py]"]
  node_fetcher["Weather fetcher<br/>[fetcher.py]"]
  node_analyzer["Alert rules<br/>[analyzer.py]"]
  node_schemas["Weather models<br/>[schemas.py]"]
  node_notifier["Telegram notifier<br/>[notifier.py]"]
end

subgraph group_storage["Persistence"]
  node_state["Alert state<br/>[estado.json]"]
  node_backenddb["Backend persistence<br/>[db.py]"]
end

subgraph group_dashboard["Web dashboard"]
  node_app["Dashboard state<br/>[App.jsx]"]
  node_client["Supabase client<br/>[supabaseClient.js]"]
  node_helpers["Weather helpers<br/>[weatherHelpers.jsx]"]
  node_search["Location search<br/>[SearchBar.jsx]"]
  node_forecast["24-hour forecast<br/>[Forecast24h.jsx]"]
  node_hourly["Hourly cards<br/>[HourlyCard.jsx]"]
  node_location["Location cards<br/>[LocationCard.jsx]"]
  node_header["Dashboard header<br/>[Header.jsx]"]
  node_tabs["Dashboard tabs<br/>[NavTabs.jsx]"]
  node_banners["Alert banners<br/>[Banners.jsx]"]
  node_alerts["Alert history<br/>[AlertsTable.jsx]"]
  node_history["Measurement history<br/>[HistoryTable.jsx]"]
end

subgraph group_integrations["External services"]
  node_supabase[("Supabase database")]
  node_telegram["Telegram Bot API"]
  node_openmeteo["Open-Meteo forecast"]
  node_geocoding["Open-Meteo geocoding"]
end

node_operator(("Dashboard user"))

node_operator -->|"uses"| node_app
node_worker -->|"loads settings"| node_config
node_worker -->|"fetches weather"| node_fetcher
node_fetcher -->|"requests forecast"| node_openmeteo
node_fetcher -->|"reads timezone"| node_config
node_fetcher -->|"returns data"| node_schemas
node_worker -->|"evaluates conditions"| node_analyzer
node_analyzer -->|"uses models"| node_schemas
node_worker -->|"saves records"| node_backenddb
node_backenddb -->|"inserts records"| node_supabase
node_backenddb -->|"uses models"| node_schemas
node_backenddb -->|"reads credentials"| node_config
node_worker -->|"sends alerts"| node_notifier
node_notifier -->|"sends message"| node_telegram
node_worker -->|"reads and writes"| node_state
node_worker -->|"uses alert levels"| node_schemas
node_app -->|"uses client"| node_client
node_client -->|"connects to"| node_supabase
node_app -->|"queries records"| node_supabase
node_app -->|"requests forecast"| node_openmeteo
node_app -->|"searches places"| node_geocoding
node_app -->|"loads locations"| node_helpers
node_app -->|"renders"| node_header
node_app -->|"renders"| node_search
node_app -->|"renders"| node_forecast
node_forecast -->|"renders"| node_hourly
node_app -->|"renders"| node_location
node_location -->|"uses wind helper"| node_helpers
node_hourly -->|"uses weather helpers"| node_helpers
node_app -->|"renders"| node_tabs
node_app -->|"renders"| node_banners
node_app -->|"renders"| node_alerts
node_app -->|"renders"| node_history

click node_worker "https://github.com/lucasraamaa/climaalert/blob/main/backend/main.py"
click node_config "https://github.com/lucasraamaa/climaalert/blob/main/backend/config.py"
click node_fetcher "https://github.com/lucasraamaa/climaalert/blob/main/backend/fetcher.py"
click node_analyzer "https://github.com/lucasraamaa/climaalert/blob/main/backend/analyzer.py"
click node_schemas "https://github.com/lucasraamaa/climaalert/blob/main/backend/schemas.py"
click node_notifier "https://github.com/lucasraamaa/climaalert/blob/main/backend/notifier.py"
click node_state "https://github.com/lucasraamaa/climaalert/blob/main/estado.json"
click node_backenddb "https://github.com/lucasraamaa/climaalert/blob/main/backend/db.py"
click node_app "https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/App.jsx"
click node_client "https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/supabaseClient.js"
click node_helpers "https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/utils/weatherHelpers.jsx"
click node_search "https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/SearchBar.jsx"
click node_forecast "https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/Forecast24h.jsx"
click node_hourly "https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/HourlyCard.jsx"
click node_location "https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/LocationCard.jsx"
click node_header "https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/Header.jsx"
click node_tabs "https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/NavTabs.jsx"
click node_banners "https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/Banners.jsx"
click node_alerts "https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/AlertsTable.jsx"
click node_history "https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/HistoryTable.jsx"

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_worker,node_config,node_fetcher,node_analyzer,node_schemas,node_notifier,node_operator toneBlue
class node_state,node_backenddb toneAmber
class node_app,node_client,node_helpers,node_search,node_forecast,node_hourly,node_location,node_header,node_tabs,node_banners,node_alerts,node_history toneMint
class node_supabase,node_telegram,node_openmeteo,node_geocoding toneRose
```

## Components

### Weather monitoring

- [Monitoring cycle](https://github.com/lucasraamaa/climaalert/blob/main/backend/main.py): `backend/main.py`
- [Runtime config](https://github.com/lucasraamaa/climaalert/blob/main/backend/config.py): `backend/config.py`
- [Weather fetcher](https://github.com/lucasraamaa/climaalert/blob/main/backend/fetcher.py): `backend/fetcher.py`
- [Alert rules](https://github.com/lucasraamaa/climaalert/blob/main/backend/analyzer.py): `backend/analyzer.py`
- [Weather models](https://github.com/lucasraamaa/climaalert/blob/main/backend/schemas.py): `backend/schemas.py`
- [Telegram notifier](https://github.com/lucasraamaa/climaalert/blob/main/backend/notifier.py): `backend/notifier.py`

### Persistence

- [Alert state](https://github.com/lucasraamaa/climaalert/blob/main/estado.json): `estado.json`
- [Backend persistence](https://github.com/lucasraamaa/climaalert/blob/main/backend/db.py): `backend/db.py`

### Web dashboard

- [Dashboard state](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Supabase client](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/supabaseClient.js): `frontend/src/supabaseClient.js`
- [Weather helpers](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/utils/weatherHelpers.jsx): `frontend/src/utils/weatherHelpers.jsx`
- [Location search](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/SearchBar.jsx): `frontend/src/components/SearchBar.jsx`
- [24-hour forecast](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/Forecast24h.jsx): `frontend/src/components/Forecast24h.jsx`
- [Hourly cards](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/HourlyCard.jsx): `frontend/src/components/HourlyCard.jsx`
- [Location cards](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/LocationCard.jsx): `frontend/src/components/LocationCard.jsx`
- [Dashboard header](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/Header.jsx): `frontend/src/components/Header.jsx`
- [Dashboard tabs](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/NavTabs.jsx): `frontend/src/components/NavTabs.jsx`
- [Alert banners](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/Banners.jsx): `frontend/src/components/Banners.jsx`
- [Alert history](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/AlertsTable.jsx): `frontend/src/components/AlertsTable.jsx`
- [Measurement history](https://github.com/lucasraamaa/climaalert/blob/main/frontend/src/components/HistoryTable.jsx): `frontend/src/components/HistoryTable.jsx`

### External services

- **Supabase database**
- **Telegram Bot API**
- **Open-Meteo forecast**
- **Open-Meteo geocoding**

### Other components

- **Dashboard user**

## Connections

- Dashboard user → Dashboard state: uses (evidence: `README.md`)
- Monitoring cycle → Runtime config: loads settings (evidence: `backend/main.py`)
- Monitoring cycle → Weather fetcher: fetches weather (evidence: `backend/main.py`)
- Weather fetcher → Open-Meteo forecast: requests forecast (evidence: `backend/fetcher.py`)
- Weather fetcher → Runtime config: reads timezone (evidence: `backend/fetcher.py`)
- Weather fetcher → Weather models: returns data (evidence: `backend/fetcher.py`)
- Monitoring cycle → Alert rules: evaluates conditions (evidence: `backend/main.py`)
- Alert rules → Weather models: uses models (evidence: `backend/analyzer.py`)
- Monitoring cycle → Backend persistence: saves records (evidence: `backend/main.py`)
- Backend persistence → Supabase database: inserts records (evidence: `backend/db.py`)
- Backend persistence → Weather models: uses models (evidence: `backend/db.py`)
- Backend persistence → Runtime config: reads credentials (evidence: `backend/db.py`)
- Monitoring cycle → Telegram notifier: sends alerts (evidence: `backend/main.py`)
- Telegram notifier → Telegram Bot API: sends message (evidence: `backend/notifier.py`)
- Monitoring cycle → Alert state: reads and writes (evidence: `backend/main.py`)
- Monitoring cycle → Weather models: uses alert levels (evidence: `backend/main.py`)
- Dashboard state → Supabase client: uses client (evidence: `frontend/src/App.jsx`)
- Supabase client → Supabase database: connects to (evidence: `frontend/src/supabaseClient.js`)
- Dashboard state → Supabase database: queries records (evidence: `frontend/src/App.jsx`)
- Dashboard state → Open-Meteo forecast: requests forecast (evidence: `frontend/src/App.jsx`)
- Dashboard state → Open-Meteo geocoding: searches places (evidence: `frontend/src/App.jsx`)
- Dashboard state → Weather helpers: loads locations (evidence: `frontend/src/App.jsx`)
- Dashboard state → Dashboard header: renders (evidence: `frontend/src/App.jsx`)
- Dashboard state → Location search: renders (evidence: `frontend/src/App.jsx`)
- Dashboard state → 24-hour forecast: renders (evidence: `frontend/src/App.jsx`)
- 24-hour forecast → Hourly cards: renders (evidence: `frontend/src/components/Forecast24h.jsx`)
- Dashboard state → Location cards: renders (evidence: `frontend/src/App.jsx`)
- Location cards → Weather helpers: uses wind helper (evidence: `frontend/src/components/LocationCard.jsx`)
- Hourly cards → Weather helpers: uses weather helpers (evidence: `frontend/src/components/HourlyCard.jsx`)
- Dashboard state → Dashboard tabs: renders (evidence: `frontend/src/App.jsx`)
- Dashboard state → Alert banners: renders (evidence: `frontend/src/App.jsx`)
- Dashboard state → Alert history: renders (evidence: `frontend/src/App.jsx`)
- Dashboard state → Measurement history: renders (evidence: `frontend/src/App.jsx`)
