# sodium16/ev-smart-grid-openenv architecture

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

- Interactive diagram: https://gitdiagram.com/sodium16/ev-smart-grid-openenv
- Repository: https://github.com/sodium16/ev-smart-grid-openenv

## Overview

This repository is an OpenEnv-compatible EV charging and V2G simulator for Indian grid conditions. The principal workflow is a client resetting an episode, submitting charge/discharge actions, receiving observations and rewards, then requesting a task score. The FastAPI layer routes these operations to the simulation and graders; the simulator models grid availability, power delivery, battery health, tariffs, and episode progress. A separate inference runner asks an OpenAI-compatible model for actions and calls the API. Relationships reflect the sampled source and README; no database or unsampled frontend behavior is inferred.

Main entry points: [`server/app.py`](https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/app.py) (FastAPI service), [`server/environment.py`](https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/environment.py) (Episode simulation), [`inference.py`](https://github.com/sodium16/ev-smart-grid-openenv/blob/main/inference.py) (Inference runner), [`server/models.py`](https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/models.py) (Action and state models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and contracts"]
  node_api["FastAPI service<br/>[app.py]"]
  node_contracts["Action and state models<br/>[models.py]"]
  node_frontend["Browser frontend<br/>[index.html]"]
end

subgraph group_simulation["EV simulation"]
  node_sim["Episode simulation<br/>[environment.py]"]
  node_history["User history generator<br/>[utils.py]"]
end

subgraph group_grading["Tasks and grading"]
  node_tasks["Task registry and graders<br/>[tasks.py]"]
end

subgraph group_policy["LLM policy runner"]
  node_runner["Inference runner<br/>[inference.py]"]
end

node_client(("API client"))
node_model(("LLM provider"))

node_client -->|"calls endpoints"| node_api
node_api -->|"resets and steps"| node_sim
node_api -->|"gets task scores"| node_tasks
node_api -->|"validates and schemas"| node_contracts
node_sim -->|"uses state models"| node_contracts
node_sim -->|"generates history"| node_history
node_api -->|"serves UI"| node_frontend
node_runner -->|"requests actions"| node_model
node_runner -->|"resets, steps, grades"| node_api

click node_api "https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/app.py"
click node_contracts "https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/models.py"
click node_frontend "https://github.com/sodium16/ev-smart-grid-openenv/blob/main/index.html"
click node_sim "https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/environment.py"
click node_history "https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/utils.py"
click node_tasks "https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/tasks.py"
click node_runner "https://github.com/sodium16/ev-smart-grid-openenv/blob/main/inference.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_api,node_contracts,node_frontend,node_client toneBlue
class node_sim,node_history toneAmber
class node_tasks toneMint
class node_runner toneRose
class node_model toneIndigo
```

## Components

### API and contracts

- [FastAPI service](https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/app.py): `server/app.py`
- [Action and state models](https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/models.py): `server/models.py`
- [Browser frontend](https://github.com/sodium16/ev-smart-grid-openenv/blob/main/index.html): `index.html`

### EV simulation

- [Episode simulation](https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/environment.py): `server/environment.py`
- [User history generator](https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/utils.py): `server/utils.py`

### Tasks and grading

- [Task registry and graders](https://github.com/sodium16/ev-smart-grid-openenv/blob/main/server/tasks.py): `server/tasks.py`

### LLM policy runner

- [Inference runner](https://github.com/sodium16/ev-smart-grid-openenv/blob/main/inference.py): `inference.py`

### Other components

- **API client**
- **LLM provider**

## Connections

- API client → FastAPI service: calls endpoints (evidence: `README.md`)
- FastAPI service → Episode simulation: resets and steps (evidence: `server/app.py`)
- FastAPI service → Task registry and graders: gets task scores (evidence: `server/app.py`)
- FastAPI service → Action and state models: validates and schemas (evidence: `server/app.py`)
- Episode simulation → Action and state models: uses state models (evidence: `server/environment.py`)
- Episode simulation → User history generator: generates history (evidence: `server/environment.py`)
- FastAPI service → Browser frontend: serves UI (evidence: `server/app.py`)
- Inference runner → LLM provider: requests actions (evidence: `inference.py`)
- Inference runner → FastAPI service: resets, steps, grades (evidence: `inference.py`)
