kaviyathamizhan/energyopt

Purpose and entry points

EnergyOpt is a full-stack energy-analytics system: it forecasts demand, flags anomalous telemetry, and generates a cost-minimizing 48-hour load schedule. The backend starts at api/main.py (uvicorn api.main:app); the SPA starts at frontend/src/main.jsx and renders the dashboard through frontend/src/App.jsx.

API application and lifecycle

FastAPI owns model loading, CORS, startup buffer warm-up, health reporting, and route registration. Runtime state is initialized from persisted artifacts and recent telemetry rather than a database.

• api/main.py

• api/state.py

• api/schemas.py

The public boundary is JSON REST/OpenAPI. Route separation permits forecast, anomaly, and optimization calls independently, while the unified prediction path orchestrates all stages.

• api/routers/predict.py

• api/routers/anomaly.py

• api/routers/optimize.py

Stateful feature boundary

The only live operational state is an in-memory sliding history buffer. It is seeded from historical CSV data, updated by incoming readings, and derives lag, rolling-window, and temporal features for inference. This makes predictions dependent on process-local history; it is not durable or multi-tenant.

• api/core/buffer.py

• data/processed/recent_history.csv

• api/services/pipeline.py

Forecasting pipeline

The pipeline normalizes engineered features and applies a primary tree forecast model plus lower/upper quantile models to create point demand and a confidence interval. Model/scaler files define a strict artifact compatibility boundary and must align with feature-column metadata.

• api/services/pipeline.py

• artifacts/models/forecast_winner.pkl

• artifacts/models/xgb_q05.pkl

• artifacts/models/xgb_q95.pkl

• artifacts/scalers/main_scaler.pkl

Anomaly guard

Anomaly assessment combines rolling statistical deviation with an Isolation Forest over selected features. It returns anomaly flags/severity alongside forecast results, allowing downstream optimization and UI decisions to expose potentially unreliable telemetry.

• api/routers/anomaly.py

• artifacts/models/isolation_forest.pkl

• artifacts/scalers/anomaly_feature_columns.json

• artifacts/DRIFT_AND_STATE_RULES.md

Optimization stage

Projected demand is passed to a linear-programming scheduler that applies time-of-use pricing and load-shifting constraints, producing an optimized profile, shifted load, and savings. The API-layer optimizer adapts the solver implementation for route/orchestrator use.

• api/core/optimizer.py

• src/optimization/lp_scheduler.py

• api/routers/optimize.py

SciPy/HiGHS is the material optimization runtime; its output depends on the forecast horizon and tariff assumptions rather than external utility services.

Frontend presentation flow

The React/Vite client submits telemetry through a configurable Axios API client, then distributes the unified response across dashboard panels for forecast bands, anomaly state, optimization, and decision summaries.

• frontend/src/services/api.js

• frontend/src/pages/Dashboard.jsx

• frontend/src/components/ForecastChart.jsx

• frontend/src/components/OptimizationPanel.jsx

• frontend/src/components/AnomalyIndicator.jsx

The frontend is deployable on Vercel and the Python API on Render; VITE_API_URL is the cross-deployment boundary. No database, authentication provider, MQTT/Kafka broker, or external telemetry service is present.