HeatGuard

Personalized heat preparedness for your home. HeatGuard analyzes your living spaces, fetches weather forecasts, and generates hour-by-hour action plans to keep you safe during heat events.

Features

• Room-level heat budget analysis — models internal gains (devices, occupants), solar gains, ventilation, and AC capacity per room
• Risk assessment — 4-tier risk levels (low/moderate/high/extreme) with time windows
• 24h SVG temperature timeline — color-coded area chart with budget status strip
• Weather integration — Open-Meteo forecasts + DWD severe weather warnings
• AI summary — optional LLM-powered 3-bullet daily briefing (Anthropic, OpenAI, Gemini)
• Care checklist — automatic reminders when vulnerable occupants are present
• Multilingual — English and German, switchable in-app
• Privacy-first — all user data stays in the browser (IndexedDB), server is stateless

Architecture

Browser (IndexedDB)          Go Server (stateless)
┌─────────────────┐         ┌──────────────────────┐
│ Profiles, Rooms │  JSON   │ /api/compute/dashboard│
│ Devices, AC     │────────>│ /api/weather/forecast │
│ Forecasts       │<────────│ /api/weather/warnings │
│ LLM Settings    │         │ /api/llm/summarize    │
└─────────────────┘         └──────────────────────┘

The Go server embeds all web assets (templates, JS, CSS, i18n) and serves them directly. No database on the server — all user data lives in the browser's IndexedDB.

Quick Start

Prerequisites

• Go 1.23+
• Node.js 18+ (for Tailwind CSS build)

Build & Run

# Install frontend dependencies
npm install

# Build (compiles CSS + Go binary)
make build

# Run
./bin/heatguard

Open http://localhost:8080 in your browser.

Development Mode

make dev

Serves files from the filesystem (hot-reload templates/JS) on port 8080.

Configuration

HeatGuard works out of the box with zero configuration. Optional server-side config for LLM:

# ~/.config/heatwave/config.yaml
llm:
  provider: anthropic  # anthropic | openai | ollama | none
  model: claude-sonnet-4-5-20250929
  # endpoint: http://localhost:11434  # for ollama

API keys for LLM providers can also be configured directly in the browser under Setup > AI Summary, stored locally in IndexedDB.

CLI Flags

Flag	Default	Description
-port	8080	HTTP listen port
-dev	false	Development mode (serve from filesystem)

Deploy

Standalone Binary

make build
./bin/heatguard -port 3000

The binary is fully self-contained — all web assets are embedded. Copy it to any Linux server and run.

Systemd Service

# /etc/systemd/system/heatguard.service
[Unit]
Description=HeatGuard heat preparedness server
After=network.target

[Service]
Type=simple
User=heatguard
ExecStart=/opt/heatguard/heatguard -port 8080
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now heatguard

Behind a Reverse Proxy (nginx)

server {
    listen 443 ssl;
    server_name heatguard.example.com;

    ssl_certificate     /etc/letsencrypt/live/heatguard.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/heatguard.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Docker

FROM golang:1.23-alpine AS build
RUN apk add --no-cache nodejs npm
WORKDIR /src
COPY . .
RUN npm install && make build

FROM alpine:3.20
COPY --from=build /src/bin/heatguard /usr/local/bin/
EXPOSE 8080
ENTRYPOINT ["heatguard"]

docker build -t heatguard .
docker run -d -p 8080:8080 heatguard

Usage Workflow

1. Create a profile — name + coordinates (auto-detect via browser geolocation)
2. Add rooms — area, orientation, windows, insulation, indoor target temp
3. Add devices & occupants — heat-producing equipment and people per room
4. Configure AC units — capacity, type, room assignments
5. Fetch forecast — pulls 3-day hourly weather data
6. View dashboard — risk level, temperature timeline, room budgets, care checklist

Development

make test    # run all tests with race detector
make build   # build CSS + binary
make dev     # run in dev mode
make clean   # remove build artifacts

License

GPL-3.0