# janeaujanssen/ems architecture

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

- Interactive diagram: https://gitdiagram.com/janeaujanssen/ems
- Repository: https://github.com/janeaujanssen/ems

## Overview

Home EMS Optimizer is a Streamlit home-energy scheduling app. A user configures Grid, PV, battery and home-load inputs; the app builds forecasts and asset models, runs a local MILP schedule, and presents charts and cost/flow results. It can also request an EVCC schedule for side-by-side comparison. The generic asset model and EV, DHW and building-thermal conversion modules represent extension capabilities, but the README says these are not wired into the current optimizer workflow. The wiring shown follows the README and sampled excerpts; unsampled details are not assumed.

Main entry points: [`app.py`](https://github.com/janeaujanssen/ems/blob/main/app.py) (Streamlit app), [`optimizer.py`](https://github.com/janeaujanssen/ems/blob/main/optimizer.py) (MILP optimizer), [`evcc_client.py`](https://github.com/janeaujanssen/ems/blob/main/evcc_client.py) (EVCC client), [`visualization.py`](https://github.com/janeaujanssen/ems/blob/main/visualization.py) (Plotly charts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["Streamlit app<br/>[app.py]"]
  node_visualization["Plotly charts<br/>[visualization.py]"]
end

subgraph group_model["Forecasts and assets"]
  node_simulator["Forecast simulator<br/>[simulator.py]"]
  node_assets["Asset abstractions<br/>[assets.py]"]
end

subgraph group_solve["Optimization"]
  node_optimizer["MILP optimizer<br/>[optimizer.py]"]
end

subgraph group_extensions["Integrations and extensions"]
  node_evcc_client["EVCC client<br/>[evcc_client.py]"]
  node_ev_conversion["EV trip conversion<br/>[ev_conversion.py]"]
  node_dhw_conversion["DHW conversion<br/>[dhw_conversion.py]"]
  node_building_conversion["Building conversion"]
end

node_user(("Home user"))
node_cbc["PuLP / CBC"]
node_evcc_service["EVCC optimizer"]

node_user -->|"configures"| node_app
node_app -->|"requests forecasts"| node_simulator
node_app -->|"builds asset models"| node_assets
node_app -->|"runs schedule"| node_optimizer
node_optimizer -->|"reads asset data"| node_assets
node_optimizer -->|"solves with"| node_cbc
node_app -->|"builds charts"| node_visualization
node_visualization -->|"returns figures"| node_app
node_app -.->|"requests comparison"| node_evcc_client
node_evcc_client -.->|"posts schedule request"| node_evcc_service
node_evcc_service -.->|"returns schedule"| node_evcc_client

click node_app "https://github.com/janeaujanssen/ems/blob/main/app.py"
click node_simulator "https://github.com/janeaujanssen/ems/blob/main/simulator.py"
click node_assets "https://github.com/janeaujanssen/ems/blob/main/assets.py"
click node_optimizer "https://github.com/janeaujanssen/ems/blob/main/optimizer.py"
click node_visualization "https://github.com/janeaujanssen/ems/blob/main/visualization.py"
click node_evcc_client "https://github.com/janeaujanssen/ems/blob/main/evcc_client.py"
click node_ev_conversion "https://github.com/janeaujanssen/ems/blob/main/ev_conversion.py"
click node_dhw_conversion "https://github.com/janeaujanssen/ems/blob/main/dhw_conversion.py"
click node_building_conversion "https://github.com/janeaujanssen/ems/blob/main/building_conversion.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_app,node_visualization,node_user toneBlue
class node_simulator,node_assets toneAmber
class node_optimizer toneMint
class node_evcc_client,node_ev_conversion,node_dhw_conversion,node_building_conversion toneRose
class node_cbc,node_evcc_service toneIndigo
```

## Components

### User interface

- [Streamlit app](https://github.com/janeaujanssen/ems/blob/main/app.py): `app.py`
- [Plotly charts](https://github.com/janeaujanssen/ems/blob/main/visualization.py): `visualization.py`

### Forecasts and assets

- [Forecast simulator](https://github.com/janeaujanssen/ems/blob/main/simulator.py): `simulator.py`
- [Asset abstractions](https://github.com/janeaujanssen/ems/blob/main/assets.py): `assets.py`

### Optimization

- [MILP optimizer](https://github.com/janeaujanssen/ems/blob/main/optimizer.py): `optimizer.py`

### Integrations and extensions

- [EVCC client](https://github.com/janeaujanssen/ems/blob/main/evcc_client.py): `evcc_client.py`
- [EV trip conversion](https://github.com/janeaujanssen/ems/blob/main/ev_conversion.py): `ev_conversion.py`
- [DHW conversion](https://github.com/janeaujanssen/ems/blob/main/dhw_conversion.py): `dhw_conversion.py`
- [Building conversion](https://github.com/janeaujanssen/ems/blob/main/building_conversion.py): `building_conversion.py`

### Other components

- **Home user**
- **PuLP / CBC**
- **EVCC optimizer**

## Connections

- Home user → Streamlit app: configures
- Streamlit app → Forecast simulator: requests forecasts
- Streamlit app → Asset abstractions: builds asset models
- Streamlit app → MILP optimizer: runs schedule
- MILP optimizer → Asset abstractions: reads asset data
- MILP optimizer → PuLP / CBC: solves with
- Streamlit app → Plotly charts: builds charts
- Plotly charts → Streamlit app: returns figures
- Streamlit app → EVCC client: requests comparison
- EVCC client → EVCC optimizer: posts schedule request
- EVCC optimizer → EVCC client: returns schedule