# gauravsrc/ev-grid-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/gauravsrc/ev-grid-intelligence
- Repository: https://github.com/gauravsrc/ev-grid-intelligence

## Overview

EV Grid Intelligence is a synthetic-digital-twin decision framework for EV charging and battery swapping across five metro clusters. Its principal workflow generates or adapts data, forecasts demand and prices, plans energy and pack allocation, simulates baseline and AI operations, then evaluates KPIs and produces analyses and reports. The README documents strategic redeployment, bidding, pricing, and execution-facing capabilities; sampled code confirms the simulation and optimization core, but does not show live dispatch integrations. Links for unsampled subsystems rely on README statements or indexed references.

Main entry points: [`evgrid/pipeline.py`](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/pipeline.py) (Pipeline orchestration), [`evgrid/simulation/runner.py`](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/simulation/runner.py) (Cluster runner), [`evgrid/simulation/engine.py`](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/simulation/engine.py) (Digital-twin engine), [`evgrid/data/io.py`](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/data/io.py) (Dataset cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and configuration"]
  node_config["Configuration<br/>[config.py]"]
  node_synthetic["Synthetic twin<br/>[synth.py]"]
  node_realdata["Real-data adapter<br/>[schema.py]"]
  node_dataio[("Dataset cache<br/>[io.py]")]
end

subgraph group_planning["Forecasting and planning"]
  node_features["Forecast features<br/>[features.py]"]
  node_forecasts["Forecast models<br/>[models.py]"]
  node_strategic["Strategic redeployment<br/>[strategic.py]"]
  node_dayahead["Day-ahead scheduler<br/>[day_ahead.py]"]
  node_lp["LP builder<br/>[lp_builder.py]"]
  node_bidding["Bid curves<br/>[bidding.py]"]
  node_pricing["Dynamic pricing<br/>[pricing.py]"]
end

subgraph group_simulation["Operational simulation"]
  node_policies["Policy definitions<br/>[policies.py]"]
  node_runner["Cluster runner<br/>[runner.py]"]
  node_engine["Digital-twin engine<br/>[engine.py]"]
  node_calibration["Baseline calibration<br/>[calibrate.py]"]
end

subgraph group_evaluation["Evaluation and analysis"]
  node_pipeline["Pipeline orchestration<br/>[pipeline.py]"]
  node_kpis["KPI computation<br/>[kpis.py]"]
  node_experiments["Experiments<br/>[experiments.py]"]
  node_figures["Analysis figures<br/>[figures.py]"]
  node_style["Figure styling<br/>[style.py]"]
end

subgraph group_outputs["Reporting"]
  node_report["Report builder<br/>[build_report.py]"]
end

node_operator(("Framework user"))
node_external["Grid and fleet systems"]

node_operator -->|"runs stages"| node_pipeline
node_config -->|"configures"| node_pipeline
node_pipeline -->|"loads data"| node_dataio
node_dataio -->|"generates on cache miss"| node_synthetic
node_realdata -.->|"adapts inputs"| node_dataio
node_pipeline -->|"runs forecasting"| node_forecasts
node_forecasts -->|"builds features"| node_features
node_pipeline -->|"plans redeployment"| node_strategic
node_pipeline -->|"runs simulation"| node_runner
node_runner -->|"loads twin data"| node_dataio
node_runner -->|"dispatches cluster tasks"| node_engine
node_runner -->|"loads forecasts"| node_forecasts
node_engine -->|"solves day-ahead plan"| node_dayahead
node_dayahead -->|"builds and solves LP"| node_lp
node_engine -->|"forms bids"| node_bidding
node_engine -->|"calculates prices"| node_pricing
node_policies -->|"selects policy"| node_runner
node_pipeline -->|"calibrates baseline"| node_calibration
node_pipeline -->|"computes results"| node_kpis
node_pipeline -->|"runs analyses"| node_experiments
node_experiments -->|"runs policy cases"| node_runner
node_pipeline -->|"builds figures"| node_figures
node_figures -->|"applies styling"| node_style
node_operator -->|"builds report"| node_report
node_external -.->|"supplies extracts"| node_realdata
node_engine -.->|"models execution"| node_external

click node_config "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/config.py"
click node_synthetic "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/data/synth.py"
click node_realdata "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/data/schema.py"
click node_dataio "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/data/io.py"
click node_pipeline "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/pipeline.py"
click node_features "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/forecasting/features.py"
click node_forecasts "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/forecasting/models.py"
click node_strategic "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/optimization/strategic.py"
click node_dayahead "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/optimization/day_ahead.py"
click node_lp "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/optimization/lp_builder.py"
click node_bidding "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/optimization/bidding.py"
click node_pricing "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/optimization/pricing.py"
click node_policies "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/simulation/policies.py"
click node_runner "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/simulation/runner.py"
click node_engine "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/simulation/engine.py"
click node_calibration "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/simulation/calibrate.py"
click node_kpis "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/simulation/kpis.py"
click node_experiments "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/analysis/experiments.py"
click node_figures "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/analysis/figures.py"
click node_style "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/analysis/style.py"
click node_report "https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/reporting/build_report.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_config,node_synthetic,node_realdata,node_dataio,node_operator toneBlue
class node_features,node_forecasts,node_strategic,node_dayahead,node_lp,node_bidding,node_pricing toneAmber
class node_policies,node_runner,node_engine,node_calibration toneMint
class node_pipeline,node_kpis,node_experiments,node_figures,node_style toneRose
class node_report,node_external toneIndigo
```

## Components

### Data and configuration

- [Configuration](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/config.py): `evgrid/config.py`
- [Synthetic twin](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/data/synth.py): `evgrid/data/synth.py`
- [Real-data adapter](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/data/schema.py): `evgrid/data/schema.py`
- [Dataset cache](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/data/io.py): `evgrid/data/io.py`

### Forecasting and planning

- [Forecast features](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/forecasting/features.py): `evgrid/forecasting/features.py`
- [Forecast models](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/forecasting/models.py): `evgrid/forecasting/models.py`
- [Strategic redeployment](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/optimization/strategic.py): `evgrid/optimization/strategic.py`
- [Day-ahead scheduler](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/optimization/day_ahead.py): `evgrid/optimization/day_ahead.py`
- [LP builder](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/optimization/lp_builder.py): `evgrid/optimization/lp_builder.py`
- [Bid curves](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/optimization/bidding.py): `evgrid/optimization/bidding.py`
- [Dynamic pricing](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/optimization/pricing.py): `evgrid/optimization/pricing.py`

### Operational simulation

- [Policy definitions](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/simulation/policies.py): `evgrid/simulation/policies.py`
- [Cluster runner](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/simulation/runner.py): `evgrid/simulation/runner.py`
- [Digital-twin engine](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/simulation/engine.py): `evgrid/simulation/engine.py`
- [Baseline calibration](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/simulation/calibrate.py): `evgrid/simulation/calibrate.py`

### Evaluation and analysis

- [Pipeline orchestration](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/pipeline.py): `evgrid/pipeline.py`
- [KPI computation](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/simulation/kpis.py): `evgrid/simulation/kpis.py`
- [Experiments](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/analysis/experiments.py): `evgrid/analysis/experiments.py`
- [Analysis figures](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/analysis/figures.py): `evgrid/analysis/figures.py`
- [Figure styling](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/analysis/style.py): `evgrid/analysis/style.py`

### Reporting

- [Report builder](https://github.com/gauravsrc/ev-grid-intelligence/blob/main/evgrid/reporting/build_report.py): `evgrid/reporting/build_report.py`

### Other components

- **Framework user**
- **Grid and fleet systems**

## Connections

- Framework user → Pipeline orchestration: runs stages (evidence: `README.md`)
- Configuration → Pipeline orchestration: configures (evidence: `evgrid/pipeline.py`)
- Pipeline orchestration → Dataset cache: loads data (evidence: `evgrid/pipeline.py`)
- Dataset cache → Synthetic twin: generates on cache miss (evidence: `evgrid/data/io.py`)
- Real-data adapter → Dataset cache: adapts inputs (evidence: `README.md`)
- Pipeline orchestration → Forecast models: runs forecasting (evidence: `evgrid/pipeline.py`)
- Forecast models → Forecast features: builds features (evidence: `evgrid/forecasting/models.py`)
- Pipeline orchestration → Strategic redeployment: plans redeployment (evidence: `evgrid/pipeline.py`)
- Pipeline orchestration → Cluster runner: runs simulation (evidence: `evgrid/pipeline.py`)
- Cluster runner → Dataset cache: loads twin data (evidence: `evgrid/simulation/runner.py`)
- Cluster runner → Digital-twin engine: dispatches cluster tasks (evidence: `evgrid/simulation/runner.py`)
- Cluster runner → Forecast models: loads forecasts (evidence: `evgrid/simulation/runner.py`)
- Digital-twin engine → Day-ahead scheduler: solves day-ahead plan (evidence: `evgrid/simulation/engine.py`)
- Day-ahead scheduler → LP builder: builds and solves LP (evidence: `evgrid/optimization/day_ahead.py`)
- Digital-twin engine → Bid curves: forms bids (evidence: `evgrid/simulation/engine.py`)
- Digital-twin engine → Dynamic pricing: calculates prices (evidence: `evgrid/simulation/engine.py`)
- Policy definitions → Cluster runner: selects policy (evidence: `evgrid/simulation/runner.py`)
- Pipeline orchestration → Baseline calibration: calibrates baseline (evidence: `evgrid/pipeline.py`)
- Pipeline orchestration → KPI computation: computes results (evidence: `evgrid/pipeline.py`)
- Pipeline orchestration → Experiments: runs analyses (evidence: `evgrid/pipeline.py`)
- Experiments → Cluster runner: runs policy cases (evidence: `evgrid/analysis/experiments.py`)
- Pipeline orchestration → Analysis figures: builds figures (evidence: `evgrid/pipeline.py`)
- Analysis figures → Figure styling: applies styling (evidence: `evgrid/analysis/figures.py`)
- Framework user → Report builder: builds report (evidence: `README.md`)
- Grid and fleet systems → Real-data adapter: supplies extracts (evidence: `README.md`)
- Digital-twin engine → Grid and fleet systems: models execution (evidence: `README.md`)
