# evcc-io/optimizer architecture

> Architecture diagram of the GitHub repository evcc-io/optimizer, 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/evcc-io/optimizer
- Repository: https://github.com/evcc-io/optimizer

## Overview

Optimizer is an HTTP service that turns home-energy forecasts, tariffs, grid limits, and battery requirements into a cost-aware schedule. The main flow is request validation and configuration, MILP construction, solving, and returning schedule data and limit violations. The README also documents battery charging goals, soft constraints, and tie-breaking peak strategies. The optimizer and app excerpts are partial; the domain-model links reflect documented capabilities, while runtime links are limited to evidenced calls.

Main entry points: [`src/optimizer/app.py`](https://github.com/evcc-io/optimizer/blob/main/src/optimizer/app.py) (API and request handling), [`src/optimizer/optimizer.py`](https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py) (MILP formulation), [`client/client.gen.go`](https://github.com/evcc-io/optimizer/blob/main/client/client.gen.go) (Go HTTP client), [`cmd/client.go`](https://github.com/evcc-io/optimizer/blob/main/cmd/client.go) (Example CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_api["API and request handling<br/>[app.py]"]
  node_request["Forecast and request"]
  node_settings["Runtime settings<br/>[settings.py]"]
  node_schedule["Schedule and violations<br/>[optimizer.py]"]
end

subgraph group_model["Optimization Model"]
  node_optimizer["Optimizer<br/>[optimizer.py]"]
  node_milp["MILP formulation<br/>[optimizer.py]"]
  node_economics["Cost and revenue<br/>[optimizer.py]"]
  node_battery["Battery limits and goals<br/>[optimizer.py]"]
  node_grid["Grid limits and penalties<br/>[optimizer.py]"]
  node_strategies["Charging strategies<br/>[optimizer.py]"]
end

subgraph group_solve["Solver Runtime"]
  node_pulp["PuLP interface"]
  node_cbc["CBC solver"]
end

subgraph group_clients["Clients"]
  node_go_client["Go HTTP client<br/>[client.gen.go]"]
  node_cli["Example CLI<br/>[client.go]"]
end

node_caller(("Energy manager"))

node_caller -->|"submits request"| node_api
node_api -->|"parses JSON"| node_request
node_api -->|"reads settings"| node_settings
node_api -->|"configures and solves"| node_optimizer
node_optimizer -->|"builds model"| node_milp
node_milp -->|"encodes objective"| node_economics
node_milp -->|"encodes constraints"| node_battery
node_milp -->|"encodes constraints"| node_grid
node_milp -->|"encodes preferences"| node_strategies
node_optimizer -->|"solves via"| node_pulp
node_pulp -->|"invokes solver"| node_cbc
node_optimizer -->|"extracts results"| node_schedule
node_api -->|"returns JSON"| node_schedule
node_caller -.->|"runs example"| node_cli
node_cli -->|"calls client"| node_go_client
node_go_client -.->|"sends HTTP"| node_api

click node_api "https://github.com/evcc-io/optimizer/blob/main/src/optimizer/app.py"
click node_settings "https://github.com/evcc-io/optimizer/blob/main/src/optimizer/settings.py"
click node_optimizer "https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py"
click node_milp "https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py"
click node_economics "https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py"
click node_battery "https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py"
click node_grid "https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py"
click node_strategies "https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py"
click node_schedule "https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py"
click node_go_client "https://github.com/evcc-io/optimizer/blob/main/client/client.gen.go"
click node_cli "https://github.com/evcc-io/optimizer/blob/main/cmd/client.go"

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_request,node_settings,node_schedule toneBlue
class node_optimizer,node_milp,node_economics,node_battery,node_grid,node_strategies toneAmber
class node_pulp,node_cbc toneMint
class node_go_client,node_cli toneRose
class node_caller toneIndigo
```

## Components

### HTTP API

- [API and request handling](https://github.com/evcc-io/optimizer/blob/main/src/optimizer/app.py): `src/optimizer/app.py`
- **Forecast and request**
- [Runtime settings](https://github.com/evcc-io/optimizer/blob/main/src/optimizer/settings.py): `src/optimizer/settings.py`
- [Schedule and violations](https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py): `src/optimizer/optimizer.py`

### Optimization Model

- [Optimizer](https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py): `src/optimizer/optimizer.py`
- [MILP formulation](https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py): `src/optimizer/optimizer.py`
- [Cost and revenue](https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py): `src/optimizer/optimizer.py`
- [Battery limits and goals](https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py): `src/optimizer/optimizer.py`
- [Grid limits and penalties](https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py): `src/optimizer/optimizer.py`
- [Charging strategies](https://github.com/evcc-io/optimizer/blob/main/src/optimizer/optimizer.py): `src/optimizer/optimizer.py`

### Solver Runtime

- **PuLP interface**
- **CBC solver**

### Clients

- [Go HTTP client](https://github.com/evcc-io/optimizer/blob/main/client/client.gen.go): `client/client.gen.go`
- [Example CLI](https://github.com/evcc-io/optimizer/blob/main/cmd/client.go): `cmd/client.go`

### Other components

- **Energy manager**

## Connections

- Energy manager → API and request handling: submits request
- API and request handling → Forecast and request: parses JSON
- API and request handling → Runtime settings: reads settings
- API and request handling → Optimizer: configures and solves
- Optimizer → MILP formulation: builds model
- MILP formulation → Cost and revenue: encodes objective
- MILP formulation → Battery limits and goals: encodes constraints
- MILP formulation → Grid limits and penalties: encodes constraints
- MILP formulation → Charging strategies: encodes preferences
- Optimizer → PuLP interface: solves via
- PuLP interface → CBC solver: invokes solver
- Optimizer → Schedule and violations: extracts results
- API and request handling → Schedule and violations: returns JSON
- Energy manager → Example CLI: runs example
- Example CLI → Go HTTP client: calls client
- Go HTTP client → API and request handling: sends HTTP