EnergyIQ

Technical stack

• React + TypeScript frontend with Tailwind CSS
• Spring Boot + JPA backend with PostgreSQL / H2
• Real-time WebSocket notifications
• JWT authentication and guest mode
• Hand-implemented Holt Linear and Holt-Winters models

Forecasting engine

Model selection is data-driven. For appliance history < 14 days EnergyIQ uses Holt Linear (level + trend). For history ≥ 14 days it uses Holt-Winters additive with a 7-day season. New appliances use a wattage × hours/day fallback with seasonal multipliers and bounded noise. Forecasts are capped to avoid unrealistic spikes.

Technical details (brief)

• Parameters: α = 0.5, β = 0.3, γ = 0.2. season length = 7. max cap = 50 kWh/day. aggregate tolerance = 15%.
• Backtest: rolling 30-day backtest for daily predictions. Evaluate with MAE, RMSE, MAPE.
• Fallback: wattage × hours/day with month-based seasonal multipliers and noise (0.95–1.05).
• Trend factor: computed from recent 30 days. Clamped to [0.9, 1.1].
• Limitations: short histories, seasonal heating/cooling shifts, sensor error, user-entered wattage inaccuracies.
• Implementation: src/main/java/com/util/TimeSeriesForecaster.java

Screenshots

Quick setup

Clone and run the backend, then start the frontend. H2 works for demo mode.

git clone https://github.com/tonna16/TrackEnergy
cd TrackEnergy/backend
mvn spring-boot:run

# in separate terminal
cd TrackEnergy/frontend
npm install && npm run dev

Reproducibility & API (how to test)

Start the backend. Use the controller endpoints below to reproduce projections and forecasts. Authentication returns user-specific forecasts when a valid session/token is provided. Guest flows use provided appliance data in the POST body and fall back to deterministic estimates.

Key endpoints

• GET /api/energy-usage/projections?timeRange=daily|weekly|monthly — authenticated user projections (GET).
• POST /api/energy-usage/projections?timeRange=daily|weekly|monthly — guest projections. Supply a JSON array of appliances in the request body.
• GET /api/energy-usage/forecasted-daily-cost — one-day cost estimate (returns fallback for guests).
• GET /api/energy-usage/annual-cost — 12-month cost projection (returns fallback for guests).
• POST /api/energy-usage?applianceId=<id>&date=<YYYY-MM-DD>&kWhUsed=<value> — log manual usage (authenticated).
• GET /api/energy-usage/daily-usage?day=today|yesterday — total kWh for a day (guest returns 0.0).

Example calls

Guest projections (no auth) — send appliances in body:

curl -X POST "http://localhost:8080/api/energy-usage/projections?timeRange=daily" \
  -H "Content-Type: application/json" \
  -d '[{"name":"Fridge","wattage":150,"hoursPerDay":24},{"name":"TV","wattage":100,"hoursPerDay":4}]'

Authenticated user projections (GET) — requires valid auth/session. Example using a token:

curl -H "Authorization: Bearer <JWT>" \
  "http://localhost:8080/api/energy-usage/projections?timeRange=weekly"

Forecasted daily cost (guest or auth) — backend returns fallback for guests:

curl "http://localhost:8080/api/energy-usage/forecasted-daily-cost"

For backtesting reproduce a rolling 30-day evaluation by calling the projections/forecast endpoints against your test dataset or by running unit tests that exercise TimeSeriesForecaster. See src/main/java/com/util/TimeSeriesForecaster.java and src/main/java/com/energytracker/service/EnergyUsageService.java.

Roadmap

• Smart-plug & meter API integrations
• Adaptive per-home learning models
• PWA / mobile improvements
• Public beta to validate forecasts with real users