From bd9c0c40a691b935e193ccb5011a1ad0509516c2 Mon Sep 17 00:00:00 2001
From: Phillip Tarrant <ptarrant@gmail.com>
Date: Mon, 26 Jan 2026 15:30:55 -0600
Subject: [PATCH] adding readme.md

---
 README.md | 173 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 173 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f17a39c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,173 @@
+# Weather Alerts
+
+A Python application that monitors weather forecasts and sends push notifications when conditions match your alert rules.
+
+## How It Works
+
+1. Queries the Visual Crossing Weather API for upcoming forecast data
+2. Evaluates forecast conditions against configurable alert rules
+3. Sends notifications to an ntfy server when alert conditions are triggered
+4. Tracks sent alerts to prevent duplicate notifications
+
+## Configuration
+
+All configuration is managed in `app/config/settings.yaml`. Copy from `settings.example.yaml` to get started:
+
+```bash
+cp app/config/settings.example.yaml app/config/settings.yaml
+```
+
+## Location Configuration
+
+Set your location in `settings.yaml` under the `weather.location` field.
+
+### Supported Location Formats
+
+Visual Crossing supports several location formats:
+
+| Format | Example | Notes |
+|--------|---------|-------|
+| City, State (US) | `"Chicago,IL"` | State abbreviation or full name |
+| City, Country | `"Paris,France"`, `"Tokyo,Japan"` | For international locations |
+| City, State, Country | `"Chicago,IL,USA"` | Most explicit format |
+| Full Address | `"620 Herndon Parkway, Herndon, Virginia, 20170, USA"` | Street-level precision |
+| ZIP/Postal Code | `"20170"` | US ZIP codes work directly |
+| Coordinates | `"40.7128,-74.0060"` | Latitude,longitude in decimal degrees |
+
+### Location Best Practices
+
+- **Include state/country** to avoid ambiguity (many cities share names like "Springfield")
+- **Coordinates are fastest** and most precise - no geocoding lookup required
+- **URL encoding is handled automatically** by the application
+
+### Coordinate Format
+
+For latitude/longitude coordinates:
+- Latitude: -90 to 90 (negative values = southern hemisphere)
+- Longitude: -180 to 180 (negative values = western hemisphere)
+- Format: `"latitude,longitude"` (e.g., `"35.8456,-86.4244"` for Viola, TN)
+
+## Alert Rules Configuration
+
+Configure alert rules under `alerts.rules` in settings.yaml. Each rule can be independently enabled or disabled.
+
+### Temperature Alerts
+
+```yaml
+temperature:
+  enabled: true
+  below: 32    # Alert when temperature falls below (freezing warning)
+  above: 95    # Alert when temperature exceeds (heat warning)
+```
+
+Both thresholds are optional - set only the ones you need.
+
+### Precipitation Alerts
+
+```yaml
+precipitation:
+  enabled: true
+  probability_above: 60  # Alert when rain/snow chance exceeds this percentage
+```
+
+### Wind Alerts
+
+```yaml
+wind:
+  enabled: true
+  speed_above: 25   # Sustained wind threshold (mph for "us" units)
+  gust_above: 30    # Wind gust threshold (mph for "us" units)
+```
+
+Either threshold can trigger an alert independently.
+
+### Severe Weather Alerts
+
+```yaml
+severe_weather:
+  enabled: true  # Forward NWS severe weather alerts from the API
+```
+
+When enabled, forwards official severe weather alerts (tornado warnings, flash flood warnings, etc.) from the National Weather Service via the Visual Crossing API.
+
+## Other Configuration Options
+
+### Weather Settings
+
+```yaml
+weather:
+  location: "viola,tn"    # Your location (see formats above)
+  hours_ahead: 24         # How many hours of forecast to check
+  unit_group: "us"        # "us" for Fahrenheit/mph, "metric" for Celsius/kph
+```
+
+### Notification Settings
+
+```yaml
+notifications:
+  ntfy:
+    server_url: "https://ntfy.sneakygeek.net"
+    topic: "weather-alerts"
+    priority: "high"              # min, low, default, high, urgent
+    tags: ["cloud", "warning"]    # Emoji tags for notifications
+```
+
+### State Management
+
+```yaml
+state:
+  file_path: "./data/state.json"
+  dedup_window_hours: 24  # Prevent duplicate alerts within this time window
+```
+
+The deduplication window prevents the same alert from being sent repeatedly. A "High Wind Warning" at 3 PM won't be sent again until 24 hours later (with default settings).
+
+### Application Settings
+
+```yaml
+app:
+  name: "weather-alerts"
+  version: "1.0.0"
+  log_level: "INFO"  # DEBUG, INFO, WARNING, ERROR
+```
+
+## Environment Variables
+
+Create a `.env` file in the project root with your secrets:
+
+```bash
+VISUALCROSSING_API_KEY=your_api_key_here
+NTFY_ACCESS_TOKEN=your_ntfy_token_here
+```
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `VISUALCROSSING_API_KEY` | Yes | API key from [Visual Crossing](https://www.visualcrossing.com/) |
+| `NTFY_ACCESS_TOKEN` | Yes* | Authentication token for ntfy server (*if server requires auth) |
+
+## Example Configuration
+
+Here's a complete example for monitoring weather in New York City:
+
+```yaml
+weather:
+  location: "New York,NY,USA"
+  hours_ahead: 12
+  unit_group: "us"
+
+alerts:
+  rules:
+    temperature:
+      enabled: true
+      below: 20     # Alert for very cold temps
+      above: 95     # Alert for heat waves
+    precipitation:
+      enabled: true
+      probability_above: 70
+    wind:
+      enabled: true
+      speed_above: 30
+      gust_above: 45
+    severe_weather:
+      enabled: true
+```