# kaviyathamizhan/energyopt architecture

> Architecture diagram of the GitHub repository kaviyathamizhan/energyopt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaviyathamizhan/energyopt
- Repository: https://github.com/kaviyathamizhan/energyopt

## Overview

#### 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.

Main entry points: [`api/main.py`](https://github.com/kaviyathamizhan/energyopt/blob/main/api/main.py) (FastAPI Application), [`frontend/src/pages/Dashboard.jsx`](https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/pages/Dashboard.jsx) (Dashboard), [`api/services/pipeline.py`](https://github.com/kaviyathamizhan/energyopt/blob/main/api/services/pipeline.py) (Forecast Pipeline), [`api/routers/predict.py`](https://github.com/kaviyathamizhan/energyopt/blob/main/api/routers/predict.py) (Prediction Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Dashboard"]
  node_spa_entry["SPA Entry<br/>React/Vite entry<br/>[main.jsx]"]
  node_app["Dashboard App<br/>React shell<br/>[App.jsx]"]
  node_dashboard["Dashboard<br/>presentation<br/>[Dashboard.jsx]"]
  node_api_client["API Client<br/>Axios client<br/>[api.js]"]
  node_forecast_chart["Forecast Chart<br/>dashboard panel<br/>[ForecastChart.jsx]"]
  node_optimization_panel["Optimization Panel<br/>dashboard panel"]
  node_anomaly_indicator["Anomaly Indicator<br/>dashboard panel"]
end

subgraph group_api["FastAPI Service"]
  node_fastapi_app["FastAPI Application<br/>API lifecycle<br/>[main.py]"]
  node_api_contracts["Request &amp; Response Schemas<br/>JSON contracts<br/>[schemas.py]"]
  node_prediction_routes["Prediction Routes<br/>REST routes<br/>[predict.py]"]
  node_anomaly_routes["Anomaly Routes<br/>REST routes<br/>[anomaly.py]"]
  node_optimization_routes["Optimization Routes<br/>REST routes<br/>[optimize.py]"]
  node_forecast_pipeline["Forecast Pipeline<br/>inference orchestration<br/>[pipeline.py]"]
end

subgraph group_state["Operational State"]
  node_runtime_state["Runtime State<br/>process-local state<br/>[state.py]"]
  node_history_buffer[("Sliding History Buffer<br/>feature state<br/>[buffer.py]")]
  node_history_csv["Recent History Seed<br/>CSV data<br/>[recent_history.csv]"]
end

subgraph group_artifacts["Model Artifacts"]
  node_forecast_models["Forecast &amp; Quantile Models<br/>serialized models"]
  node_main_scaler["Feature Scaler<br/>serialized scaler<br/>[main_scaler.pkl]"]
  node_anomaly_model["Isolation Forest<br/>anomaly model"]
  node_anomaly_rules["Anomaly Feature Rules<br/>feature metadata"]
end

subgraph group_optimization["Optimization Runtime"]
  node_api_optimizer["API Optimizer Adapter<br/>scheduler adapter<br/>[optimizer.py]"]
  node_lp_scheduler{{"LP Scheduler<br/>SciPy/HiGHS solver<br/>[lp_scheduler.py]"}}
end

node_spa_entry -->|"renders"| node_app
node_app -->|"hosts"| node_dashboard
node_dashboard -->|"submits telemetry"| node_api_client
node_api_client -->|"JSON REST / OpenAPI"| node_fastapi_app
node_fastapi_app -->|"validates"| node_api_contracts
node_fastapi_app -->|"registers"| node_prediction_routes
node_fastapi_app -->|"registers"| node_anomaly_routes
node_fastapi_app -->|"registers"| node_optimization_routes
node_fastapi_app -->|"initializes"| node_runtime_state
node_runtime_state -->|"owns"| node_history_buffer
node_history_csv -->|"seeds"| node_history_buffer
node_prediction_routes -->|"orchestrates"| node_forecast_pipeline
node_prediction_routes -->|"assesses telemetry"| node_anomaly_routes
node_prediction_routes -->|"schedules demand"| node_api_optimizer
node_history_buffer -->|"engineered features"| node_forecast_pipeline
node_forecast_pipeline -->|"updates readings"| node_history_buffer
node_forecast_models -->|"point and quantile inference"| node_forecast_pipeline
node_main_scaler -->|"normalizes features"| node_forecast_pipeline
node_anomaly_routes -->|"scores features"| node_anomaly_model
node_anomaly_rules -->|"selected features and rules"| node_anomaly_routes
node_api_optimizer -->|"adapts solver"| node_lp_scheduler
node_forecast_pipeline -->|"48-hour projected demand"| node_api_optimizer
node_prediction_routes -->|"unified response"| node_dashboard
node_dashboard -->|"forecast bands"| node_forecast_chart
node_dashboard -->|"profile and savings"| node_optimization_panel
node_dashboard -->|"flag and severity"| node_anomaly_indicator

click node_spa_entry "https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/main.jsx"
click node_app "https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/App.jsx"
click node_dashboard "https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/pages/Dashboard.jsx"
click node_api_client "https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/services/api.js"
click node_forecast_chart "https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/components/ForecastChart.jsx"
click node_optimization_panel "https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/components/OptimizationPanel.jsx"
click node_anomaly_indicator "https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/components/AnomalyIndicator.jsx"
click node_fastapi_app "https://github.com/kaviyathamizhan/energyopt/blob/main/api/main.py"
click node_api_contracts "https://github.com/kaviyathamizhan/energyopt/blob/main/api/schemas.py"
click node_prediction_routes "https://github.com/kaviyathamizhan/energyopt/blob/main/api/routers/predict.py"
click node_anomaly_routes "https://github.com/kaviyathamizhan/energyopt/blob/main/api/routers/anomaly.py"
click node_optimization_routes "https://github.com/kaviyathamizhan/energyopt/blob/main/api/routers/optimize.py"
click node_runtime_state "https://github.com/kaviyathamizhan/energyopt/blob/main/api/state.py"
click node_history_buffer "https://github.com/kaviyathamizhan/energyopt/blob/main/api/core/buffer.py"
click node_history_csv "https://github.com/kaviyathamizhan/energyopt/blob/main/data/processed/recent_history.csv"
click node_forecast_pipeline "https://github.com/kaviyathamizhan/energyopt/blob/main/api/services/pipeline.py"
click node_forecast_models "https://github.com/kaviyathamizhan/energyopt/blob/main/artifacts/models/forecast_winner.pkl"
click node_main_scaler "https://github.com/kaviyathamizhan/energyopt/blob/main/artifacts/scalers/main_scaler.pkl"
click node_anomaly_model "https://github.com/kaviyathamizhan/energyopt/blob/main/artifacts/models/isolation_forest.pkl"
click node_anomaly_rules "https://github.com/kaviyathamizhan/energyopt/blob/main/artifacts/scalers/anomaly_feature_columns.json"
click node_api_optimizer "https://github.com/kaviyathamizhan/energyopt/blob/main/api/core/optimizer.py"
click node_lp_scheduler "https://github.com/kaviyathamizhan/energyopt/blob/main/src/optimization/lp_scheduler.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spa_entry,node_app,node_dashboard,node_api_client,node_forecast_chart,node_optimization_panel,node_anomaly_indicator toneBlue
class node_fastapi_app,node_api_contracts,node_prediction_routes,node_anomaly_routes,node_optimization_routes,node_forecast_pipeline toneAmber
class node_runtime_state,node_history_buffer,node_history_csv toneMint
class node_forecast_models,node_main_scaler,node_anomaly_model,node_anomaly_rules toneRose
class node_api_optimizer,node_lp_scheduler toneIndigo
```

## Components

### React Dashboard

- [SPA Entry](https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/main.jsx): React/Vite entry · `frontend/src/main.jsx`
- [Dashboard App](https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/App.jsx): React shell · `frontend/src/App.jsx`
- [Dashboard](https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/pages/Dashboard.jsx): presentation · Distributes unified results to decision panels. · `frontend/src/pages/Dashboard.jsx`
- [API Client](https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/services/api.js): Axios client · Uses VITE_API_URL as the cross-deployment boundary. · `frontend/src/services/api.js`
- [Forecast Chart](https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/components/ForecastChart.jsx): dashboard panel · `frontend/src/components/ForecastChart.jsx`
- [Optimization Panel](https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/components/OptimizationPanel.jsx): dashboard panel · `frontend/src/components/OptimizationPanel.jsx`
- [Anomaly Indicator](https://github.com/kaviyathamizhan/energyopt/blob/main/frontend/src/components/AnomalyIndicator.jsx): dashboard panel · `frontend/src/components/AnomalyIndicator.jsx`

### FastAPI Service

- [FastAPI Application](https://github.com/kaviyathamizhan/energyopt/blob/main/api/main.py): API lifecycle · Loads artifacts, configures CORS, warms state, and registers routes. · `api/main.py`
- [Request & Response Schemas](https://github.com/kaviyathamizhan/energyopt/blob/main/api/schemas.py): JSON contracts · `api/schemas.py`
- [Prediction Routes](https://github.com/kaviyathamizhan/energyopt/blob/main/api/routers/predict.py): REST routes · Unified prediction orchestrates forecast, anomaly, and scheduling. · `api/routers/predict.py`
- [Anomaly Routes](https://github.com/kaviyathamizhan/energyopt/blob/main/api/routers/anomaly.py): REST routes · `api/routers/anomaly.py`
- [Optimization Routes](https://github.com/kaviyathamizhan/energyopt/blob/main/api/routers/optimize.py): REST routes · `api/routers/optimize.py`
- [Forecast Pipeline](https://github.com/kaviyathamizhan/energyopt/blob/main/api/services/pipeline.py): inference orchestration · Normalizes features and produces point demand plus confidence bounds. · `api/services/pipeline.py`

### Operational State

- [Runtime State](https://github.com/kaviyathamizhan/energyopt/blob/main/api/state.py): process-local state · `api/state.py`
- [Sliding History Buffer](https://github.com/kaviyathamizhan/energyopt/blob/main/api/core/buffer.py): feature state · Process-local, non-durable history deriving lag, rolling, and temporal features. · `api/core/buffer.py`
- [Recent History Seed](https://github.com/kaviyathamizhan/energyopt/blob/main/data/processed/recent_history.csv): CSV data · `data/processed/recent_history.csv`

### Model Artifacts

- [Forecast & Quantile Models](https://github.com/kaviyathamizhan/energyopt/blob/main/artifacts/models/forecast_winner.pkl): serialized models · Artifact compatibility must match feature-column metadata. · `artifacts/models/forecast_winner.pkl`
- [Feature Scaler](https://github.com/kaviyathamizhan/energyopt/blob/main/artifacts/scalers/main_scaler.pkl): serialized scaler · `artifacts/scalers/main_scaler.pkl`
- [Isolation Forest](https://github.com/kaviyathamizhan/energyopt/blob/main/artifacts/models/isolation_forest.pkl): anomaly model · `artifacts/models/isolation_forest.pkl`
- [Anomaly Feature Rules](https://github.com/kaviyathamizhan/energyopt/blob/main/artifacts/scalers/anomaly_feature_columns.json): feature metadata · Defines selected anomaly features and drift/state rules. · `artifacts/scalers/anomaly_feature_columns.json`

### Optimization Runtime

- [API Optimizer Adapter](https://github.com/kaviyathamizhan/energyopt/blob/main/api/core/optimizer.py): scheduler adapter · `api/core/optimizer.py`
- [LP Scheduler](https://github.com/kaviyathamizhan/energyopt/blob/main/src/optimization/lp_scheduler.py): SciPy/HiGHS solver · Applies tariffs and load-shifting constraints over the forecast horizon. · `src/optimization/lp_scheduler.py`

## Connections

- SPA Entry → Dashboard App: renders
- Dashboard App → Dashboard: hosts
- Dashboard → API Client: submits telemetry
- API Client → FastAPI Application: JSON REST / OpenAPI
- FastAPI Application → Request & Response Schemas: validates
- FastAPI Application → Prediction Routes: registers
- FastAPI Application → Anomaly Routes: registers
- FastAPI Application → Optimization Routes: registers
- FastAPI Application → Runtime State: initializes
- Runtime State → Sliding History Buffer: owns
- Recent History Seed → Sliding History Buffer: seeds
- Prediction Routes → Forecast Pipeline: orchestrates
- Prediction Routes → Anomaly Routes: assesses telemetry
- Prediction Routes → API Optimizer Adapter: schedules demand
- Sliding History Buffer → Forecast Pipeline: engineered features
- Forecast Pipeline → Sliding History Buffer: updates readings
- Forecast & Quantile Models → Forecast Pipeline: point and quantile inference
- Feature Scaler → Forecast Pipeline: normalizes features
- Anomaly Routes → Isolation Forest: scores features
- Anomaly Feature Rules → Anomaly Routes: selected features and rules
- API Optimizer Adapter → LP Scheduler: adapts solver
- Forecast Pipeline → API Optimizer Adapter: 48-hour projected demand
- Prediction Routes → Dashboard: unified response
- Dashboard → Forecast Chart: forecast bands
- Dashboard → Optimization Panel: profile and savings
- Dashboard → Anomaly Indicator: flag and severity