feat: add weather pooler and config

1 files changed, 92 insertions, 11 deletions

diff --git a/README.md b/README.md
index 61248fd..fc7382b 100644
--- a/README.md
+++ b/README.md
@@ -4,11 +4,14 @@ Silmataivas is a weather monitoring service that sends personalized alerts based
 
 ## Features
 
-- Weather monitoring using OpenWeatherMap API
-- Custom weather thresholds per user
-- Flexible notifications: NTFY (push) and SMTP (email)
-- User-specific configuration
-- RESTful API for all resources
+- **Weather monitoring using OpenWeatherMap API**: Automatic hourly weather data fetching for all users with locations
+- **Location-based weather tracking**: Each user can set their location for personalized weather monitoring
+- **Custom weather thresholds per user**: Define temperature, rain, and wind speed thresholds with custom operators
+- **Automatic threshold checking**: After fetching weather data, the system automatically checks if any thresholds are exceeded
+- **Flexible notifications**: NTFY (push) and SMTP (email) notifications when thresholds are exceeded
+- **User-specific configuration**: Each user has their own settings and thresholds
+- **RESTful API for all resources**: Complete API for managing users, locations, thresholds, and notifications
+- **Background task scheduling**: Weather polling runs automatically every hour in the background
 
 ## Project Structure
 
@@ -28,21 +31,99 @@ Silmataivas is a weather monitoring service that sends personalized alerts based
 
 ```bash
 # Clone the repository
- git clone https://codeberg.org/silmataivas/silmataivas.git
- cd silmataivas
+git clone https://codeberg.org/silmataivas/silmataivas.git
+cd silmataivas
+
+# Set required environment variables
+export OPENWEATHERMAP_API_KEY="your_api_key_here"
 
 # Build and run
- cargo build --release
- ./target/release/silmataivas
+cargo build --release
+./target/release/silmataivas
 ```
 
-The server will listen on port 4000 by default. You can set the `DATABASE_URL` environment variable to change the database location.
+The server will:
+- Listen on port 4000 by default (configurable via `PORT` environment variable)
+- Use `~/.local/share/silmataivas/silmataivas.db` as the default database location
+- Create the database directory automatically if it doesn't exist
+- Generate an admin token automatically if none is provided
 
 ### Using Docker
 
 ```bash
 docker build -t silmataivas .
-docker run -p 4000:4000 -e DATABASE_URL=sqlite:///data/silmataivas.db silmataivas
+docker run -p 4000:4000 \
+  -e OPENWEATHERMAP_API_KEY="your_api_key_here" \
+  -e DATABASE_URL="sqlite:///data/silmataivas.db" \
+  silmataivas
+```
+
+## Weather Polling
+
+The application automatically fetches weather data from OpenWeatherMap API every hour for all users who have set their locations. Here's how it works:
+
+### Automatic Weather Data Collection
+
+1. **Hourly Scheduling**: The weather poller runs every hour in the background
+2. **Location Rounding**: Coordinates are rounded to 2 decimal places (~1km precision) to reduce API calls for nearby locations
+3. **Async Processing**: Each user-location combination is processed in parallel for efficiency
+4. **Data Storage**: Weather data is stored in the `weather_api_data` table for future reference
+
+### Threshold Checking
+
+After fetching weather data, the system automatically:
+1. Checks all enabled thresholds for the user
+2. Compares current weather conditions against threshold values
+3. Sends notifications (NTFY/SMTP) if thresholds are exceeded
+4. Only sends one notification per check to avoid spam
+
+### Manual Weather Check
+
+You can manually trigger a weather check for testing:
+
+```bash
+cargo run -- check-weather
+```
+
+### Environment Variables
+
+The application uses the following environment variables for configuration:
+
+#### Required
+- `OPENWEATHERMAP_API_KEY`: Your OpenWeatherMap API key for weather data access
+
+#### Optional
+- `DATABASE_URL`: Database connection string (defaults to XDG_DATA_HOME or ~/.local/share)
+- `XDG_DATA_HOME`: Custom data directory (defaults to ~/.local/share)
+- `ADMIN_TOKEN`: Initial admin user token (auto-generated if not set)
+- `PORT`: Server port (default: 4000)
+- `HOST`: Server host (default: 0.0.0.0)
+- `LOG_LEVEL`: Logging level (default: info)
+
+#### Database URL Fallback Logic
+
+If `DATABASE_URL` is not set, the application will use the following fallback path:
+1. `$XDG_DATA_HOME/silmataivas/silmataivas.db` (if XDG_DATA_HOME is set)
+2. `~/.local/share/silmataivas/silmataivas.db` (default fallback)
+
+The directory will be created automatically if it doesn't exist.
+
+#### Example Configuration
+
+```bash
+# Required
+export OPENWEATHERMAP_API_KEY="your_api_key_here"
+
+# Optional - custom database location
+export DATABASE_URL="sqlite:///path/to/custom/database.db"
+
+# Optional - custom data directory
+export XDG_DATA_HOME="/custom/data/path"
+
+# Optional - server configuration
+export PORT="8080"
+export HOST="127.0.0.1"
+export LOG_LEVEL="debug"
 ```
 
 ## API Usage