# kyathamkarthik/gridsense-ml architecture

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

- Interactive diagram: https://gitdiagram.com/kyathamkarthik/gridsense-ml
- Repository: https://github.com/kyathamkarthik/gridsense-ml

## Overview

GridSense-ML forecasts appliance electricity demand and analyzes peak-load events. The main workflow is launched by the training pipeline: load and clean timestamped data, engineer causal features, split chronologically, benchmark and fit regression models, evaluate holdout forecasts, then calculate peak metrics and save artifacts for the Streamlit dashboard. The graph separates these domain stages from the dashboard’s inspection capabilities. Relationships follow the pipeline and dashboard excerpts or README; unsampled configuration and implementation details are not inferred.

Main entry points: [`train_pipeline.py`](https://github.com/kyathamkarthik/gridsense-ml/blob/main/train_pipeline.py) (Training pipeline), [`app.py`](https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.py) (Streamlit dashboard), [`src/evaluation.py`](https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/evaluation.py) (Evaluation artifacts), [`src/data_processing.py`](https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/data_processing.py) (Data preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Forecast workflow"]
  node_pipeline["Training pipeline<br/>[train_pipeline.py]"]
  node_preparation["Data preparation<br/>[data_processing.py]"]
  node_features["Causal features<br/>[features.py]"]
  node_training["Model training<br/>[models.py]"]
end

subgraph group_analytics["Evaluation analytics"]
  node_evaluation["Forecast evaluation<br/>[evaluation.py]"]
  node_peak["Peak intelligence"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_app["Streamlit dashboard<br/>[app.py]"]
  node_performance["Model performance<br/>[app.py]"]
  node_forecast_view["Forecast timeline<br/>[app.py]"]
  node_importance_view["Feature importance<br/>[app.py]"]
  node_hourly_view["Hourly diagnostics<br/>[app.py]"]
  node_leaderboard_view["Model leaderboard<br/>[app.py]"]
end

subgraph group_data["Data and artifacts"]
  node_rawdata["Energy dataset"]
  node_artifacts[("Evaluation artifacts<br/>[evaluation.py]")]
end

node_operator(("Analyst / operator"))

node_operator -->|"runs training"| node_pipeline
node_pipeline -->|"reads dataset"| node_rawdata
node_pipeline -->|"calls preparation"| node_preparation
node_pipeline -->|"calls engineering"| node_features
node_pipeline -->|"splits and fits"| node_training
node_pipeline -->|"evaluates forecasts"| node_evaluation
node_pipeline -->|"evaluates peaks"| node_peak
node_evaluation -->|"writes results"| node_artifacts
node_pipeline -->|"writes threshold"| node_artifacts
node_operator -->|"opens dashboard"| node_dashboard_app
node_dashboard_app -->|"loads results"| node_artifacts
node_dashboard_app -->|"shows metrics"| node_performance
node_dashboard_app -->|"plots forecasts"| node_forecast_view
node_dashboard_app -->|"plots importances"| node_importance_view
node_dashboard_app -->|"plots hourly errors"| node_hourly_view
node_dashboard_app -->|"shows leaderboard"| node_leaderboard_view

click node_pipeline "https://github.com/kyathamkarthik/gridsense-ml/blob/main/train_pipeline.py"
click node_rawdata "https://github.com/kyathamkarthik/gridsense-ml/blob/main/data/raw/energydata_complete.csv"
click node_preparation "https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/data_processing.py"
click node_features "https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/features.py"
click node_training "https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/models.py"
click node_evaluation "https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/evaluation.py"
click node_peak "https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/peak_intelligence.py"
click node_artifacts "https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/evaluation.py"
click node_dashboard_app "https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.py"
click node_performance "https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.py"
click node_forecast_view "https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.py"
click node_importance_view "https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.py"
click node_hourly_view "https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.py"
click node_leaderboard_view "https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.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_pipeline,node_preparation,node_features,node_training toneBlue
class node_evaluation,node_peak toneAmber
class node_dashboard_app,node_performance,node_forecast_view,node_importance_view,node_hourly_view,node_leaderboard_view toneMint
class node_rawdata,node_artifacts toneRose
class node_operator toneIndigo
```

## Components

### Forecast workflow

- [Training pipeline](https://github.com/kyathamkarthik/gridsense-ml/blob/main/train_pipeline.py): `train_pipeline.py`
- [Data preparation](https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/data_processing.py): `src/data_processing.py`
- [Causal features](https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/features.py): `src/features.py`
- [Model training](https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/models.py): `src/models.py`

### Evaluation analytics

- [Forecast evaluation](https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/evaluation.py): `src/evaluation.py`
- [Peak intelligence](https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/peak_intelligence.py): `src/peak_intelligence.py`

### Dashboard

- [Streamlit dashboard](https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.py): `app.py`
- [Model performance](https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.py): `app.py`
- [Forecast timeline](https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.py): `app.py`
- [Feature importance](https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.py): `app.py`
- [Hourly diagnostics](https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.py): `app.py`
- [Model leaderboard](https://github.com/kyathamkarthik/gridsense-ml/blob/main/app.py): `app.py`

### Data and artifacts

- [Energy dataset](https://github.com/kyathamkarthik/gridsense-ml/blob/main/data/raw/energydata_complete.csv): `data/raw/energydata_complete.csv`
- [Evaluation artifacts](https://github.com/kyathamkarthik/gridsense-ml/blob/main/src/evaluation.py): `src/evaluation.py`

### Other components

- **Analyst / operator**

## Connections

- Analyst / operator → Training pipeline: runs training (evidence: `README.md`)
- Training pipeline → Energy dataset: reads dataset (evidence: `README.md`)
- Training pipeline → Data preparation: calls preparation (evidence: `train_pipeline.py`)
- Training pipeline → Causal features: calls engineering (evidence: `train_pipeline.py`)
- Training pipeline → Model training: splits and fits (evidence: `train_pipeline.py`)
- Training pipeline → Forecast evaluation: evaluates forecasts (evidence: `train_pipeline.py`)
- Training pipeline → Peak intelligence: evaluates peaks (evidence: `train_pipeline.py`)
- Forecast evaluation → Evaluation artifacts: writes results (evidence: `src/evaluation.py`)
- Training pipeline → Evaluation artifacts: writes threshold (evidence: `train_pipeline.py`)
- Analyst / operator → Streamlit dashboard: opens dashboard (evidence: `README.md`)
- Streamlit dashboard → Evaluation artifacts: loads results (evidence: `app.py`)
- Streamlit dashboard → Model performance: shows metrics (evidence: `app.py`)
- Streamlit dashboard → Forecast timeline: plots forecasts (evidence: `app.py`)
- Streamlit dashboard → Feature importance: plots importances (evidence: `app.py`)
- Streamlit dashboard → Hourly diagnostics: plots hourly errors (evidence: `app.py`)
- Streamlit dashboard → Model leaderboard: shows leaderboard (evidence: `app.py`)