# ravvah/ecoshift architecture

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

- Interactive diagram: https://gitdiagram.com/ravvah/ecoshift
- Repository: https://github.com/ravvah/ecoshift
- Video tour (about a minute): https://gitdiagram.com/ravvah/ecoshift/video

## Overview

EcoShift is an experimental predict-then-optimize decision-science system for scheduling flexible industrial loads against electricity-price and carbon forecasts. The forecast service exposes predictions and has a separate model-development path for feature engineering, training, evaluation, and MLflow tracking. The optimizer service defines load constraints and solver implementations for producing schedules. The README describes decision-regret analysis as a goal, but no regret-analysis implementation appears in the supplied tree. The optimizer’s runtime wiring and any connection between the two services are not established by the excerpts.

Main entry points: [`forecast_service/src/forecast_service/app/api/v1/endpoints/predict.py`](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/api/v1/endpoints/predict.py) (Predict endpoint), [`optimizer_service/src/optimizer_service/solver/scipy_lp_solver.py`](https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/solver/scipy_lp_solver.py) (SciPy LP solver), [`forecast_service/src/forecast_service/app/services/predictor.py`](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/services/predictor.py) (Prediction service), [`forecast_service/src/forecast_service/model/forecaster.py`](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/model/forecaster.py) (Energy forecaster)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_forecast_api["Forecast API"]
  node_forecast_app["Forecast app<br/>[main.py]"]
  node_forecast_routes["Forecast routes<br/>[router.py]"]
  node_predict_endpoint["Predict endpoint<br/>[predict.py]"]
  node_health_endpoint["Health endpoint<br/>[health.py]"]
  node_api_dependencies["API dependencies<br/>[dependencies.py]"]
  node_security["API security<br/>[security.py]"]
  node_predictor["Prediction service<br/>[predictor.py]"]
end

subgraph group_forecast_models["Forecast Models"]
  node_data_loader["Data loading<br/>[data_loader.py]"]
  node_feature_engineer["Feature engineering<br/>[features.py]"]
  node_forecaster["Energy forecaster<br/>[forecaster.py]"]
  node_trainer["Model training<br/>[trainer.py]"]
  node_evaluator["Model evaluation<br/>[evaluator.py]"]
  node_tuner["Hyperparameter tuning<br/>[tuner.py]"]
  node_mlflow_tracker["MLflow tracking<br/>[mlflow_tracker.py]"]
end

subgraph group_optimization["Optimization"]
  node_optimize_endpoint["Optimize endpoint<br/>[optimize.py]"]
  node_optimizer_service["Optimization service<br/>[optimizer.py]"]
  node_load_constraint["Load constraints<br/>[constraints.py]"]
  node_solver_factory["Solver factory<br/>[factory.py]"]
  node_solver_base["Solver interface<br/>[base.py]"]
  node_scipy_solver["SciPy LP solver<br/>[scipy_lp_solver.py]"]
  node_optimization_result["Schedule result<br/>[result.py]"]
end

subgraph group_shared_contracts["Contracts"]
  node_request_schema["Forecast request<br/>[request.py]"]
  node_response_schema["Forecast response<br/>[response.py]"]
  node_optimization_contracts["Optimization contracts"]
end

node_caller(("API caller"))
node_mlflow_registry[("MLflow registry")]
node_scipy_library["SciPy optimizer"]

node_caller -->|"requests forecast"| node_predict_endpoint
node_forecast_app -->|"loads and warms"| node_predictor
node_forecast_app -->|"mounts routes"| node_forecast_routes
node_forecast_routes -->|"registers route"| node_predict_endpoint
node_forecast_routes -->|"registers route"| node_health_endpoint
node_predict_endpoint -->|"resolves service"| node_api_dependencies
node_predict_endpoint -->|"checks API key"| node_security
node_predict_endpoint -->|"calls prediction"| node_predictor
node_predict_endpoint -->|"accepts request"| node_request_schema
node_predict_endpoint -->|"returns response"| node_response_schema
node_predictor -->|"reads history"| node_request_schema
node_predictor -->|"builds forecast"| node_response_schema
node_predictor -->|"loads models"| node_mlflow_tracker
node_forecaster -->|"transforms features"| node_feature_engineer
node_trainer -->|"fits and predicts"| node_forecaster
node_trainer -->|"evaluates folds"| node_evaluator
node_tuner -->|"uses models"| node_forecaster
node_tuner -->|"runs training"| node_trainer
node_mlflow_tracker -->|"logs model"| node_forecaster
node_mlflow_tracker -->|"loads and registers"| node_mlflow_registry
node_optimize_endpoint -.->|"delegates optimization"| node_optimizer_service
node_optimizer_service -.->|"uses API schemas"| node_optimization_contracts
node_optimizer_service -.->|"selects solver"| node_solver_factory
node_solver_factory -->|"creates solver"| node_scipy_solver
node_scipy_solver -->|"implements interface"| node_solver_base
node_scipy_solver -->|"uses constraints"| node_load_constraint
node_scipy_solver -->|"builds schedule"| node_optimization_result
node_scipy_solver -->|"solves LP"| node_scipy_library

click node_forecast_app "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/main.py"
click node_forecast_routes "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/api/v1/router.py"
click node_predict_endpoint "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/api/v1/endpoints/predict.py"
click node_health_endpoint "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/api/v1/endpoints/health.py"
click node_api_dependencies "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/api/dependencies.py"
click node_security "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/core/security.py"
click node_predictor "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/services/predictor.py"
click node_request_schema "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/schemas/request.py"
click node_response_schema "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/schemas/response.py"
click node_data_loader "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/data/data_loader.py"
click node_feature_engineer "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/features/features.py"
click node_forecaster "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/model/forecaster.py"
click node_trainer "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/model/trainer.py"
click node_evaluator "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/model/evaluator.py"
click node_tuner "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/model/tuner.py"
click node_mlflow_tracker "https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/tracking/mlflow_tracker.py"
click node_optimize_endpoint "https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/app/api/v1/endpoints/optimize.py"
click node_optimizer_service "https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/app/services/optimizer.py"
click node_optimization_contracts "https://github.com/ravvah/ecoshift/tree/main/optimizer_service/src/optimizer_service/app/schemas"
click node_load_constraint "https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/domain/constraints.py"
click node_solver_factory "https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/solver/factory.py"
click node_solver_base "https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/solver/base.py"
click node_scipy_solver "https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/solver/scipy_lp_solver.py"
click node_optimization_result "https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/domain/result.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_forecast_app,node_forecast_routes,node_predict_endpoint,node_health_endpoint,node_api_dependencies,node_security,node_predictor toneBlue
class node_data_loader,node_feature_engineer,node_forecaster,node_trainer,node_evaluator,node_tuner,node_mlflow_tracker,node_mlflow_registry toneAmber
class node_optimize_endpoint,node_optimizer_service,node_load_constraint,node_solver_factory,node_solver_base,node_scipy_solver,node_optimization_result,node_caller toneMint
class node_request_schema,node_response_schema,node_optimization_contracts toneRose
class node_scipy_library toneIndigo
```

## Components

### Forecast API

- [Forecast app](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/main.py): `forecast_service/src/forecast_service/app/main.py`
- [Forecast routes](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/api/v1/router.py): `forecast_service/src/forecast_service/app/api/v1/router.py`
- [Predict endpoint](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/api/v1/endpoints/predict.py): `forecast_service/src/forecast_service/app/api/v1/endpoints/predict.py`
- [Health endpoint](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/api/v1/endpoints/health.py): `forecast_service/src/forecast_service/app/api/v1/endpoints/health.py`
- [API dependencies](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/api/dependencies.py): `forecast_service/src/forecast_service/app/api/dependencies.py`
- [API security](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/core/security.py): `forecast_service/src/forecast_service/app/core/security.py`
- [Prediction service](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/services/predictor.py): `forecast_service/src/forecast_service/app/services/predictor.py`

### Forecast Models

- [Data loading](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/data/data_loader.py): `forecast_service/src/forecast_service/data/data_loader.py`
- [Feature engineering](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/features/features.py): `forecast_service/src/forecast_service/features/features.py`
- [Energy forecaster](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/model/forecaster.py): `forecast_service/src/forecast_service/model/forecaster.py`
- [Model training](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/model/trainer.py): `forecast_service/src/forecast_service/model/trainer.py`
- [Model evaluation](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/model/evaluator.py): `forecast_service/src/forecast_service/model/evaluator.py`
- [Hyperparameter tuning](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/model/tuner.py): `forecast_service/src/forecast_service/model/tuner.py`
- [MLflow tracking](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/tracking/mlflow_tracker.py): `forecast_service/src/forecast_service/tracking/mlflow_tracker.py`

### Optimization

- [Optimize endpoint](https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/app/api/v1/endpoints/optimize.py): `optimizer_service/src/optimizer_service/app/api/v1/endpoints/optimize.py`
- [Optimization service](https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/app/services/optimizer.py): `optimizer_service/src/optimizer_service/app/services/optimizer.py`
- [Load constraints](https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/domain/constraints.py): `optimizer_service/src/optimizer_service/domain/constraints.py`
- [Solver factory](https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/solver/factory.py): `optimizer_service/src/optimizer_service/solver/factory.py`
- [Solver interface](https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/solver/base.py): `optimizer_service/src/optimizer_service/solver/base.py`
- [SciPy LP solver](https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/solver/scipy_lp_solver.py): `optimizer_service/src/optimizer_service/solver/scipy_lp_solver.py`
- [Schedule result](https://github.com/ravvah/ecoshift/blob/main/optimizer_service/src/optimizer_service/domain/result.py): `optimizer_service/src/optimizer_service/domain/result.py`

### Contracts

- [Forecast request](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/schemas/request.py): `forecast_service/src/forecast_service/app/schemas/request.py`
- [Forecast response](https://github.com/ravvah/ecoshift/blob/main/forecast_service/src/forecast_service/app/schemas/response.py): `forecast_service/src/forecast_service/app/schemas/response.py`
- [Optimization contracts](https://github.com/ravvah/ecoshift/tree/main/optimizer_service/src/optimizer_service/app/schemas): `optimizer_service/src/optimizer_service/app/schemas`

### Other components

- **API caller**
- **MLflow registry**
- **SciPy optimizer**

## Connections

- API caller → Predict endpoint: requests forecast
- Forecast app → Prediction service: loads and warms (evidence: `forecast_service/src/forecast_service/app/main.py`)
- Forecast app → Forecast routes: mounts routes (evidence: `forecast_service/src/forecast_service/app/main.py`)
- Forecast routes → Predict endpoint: registers route (evidence: `forecast_service/src/forecast_service/app/api/v1/router.py`)
- Forecast routes → Health endpoint: registers route (evidence: `forecast_service/src/forecast_service/app/api/v1/router.py`)
- Predict endpoint → API dependencies: resolves service (evidence: `forecast_service/src/forecast_service/app/api/v1/endpoints/predict.py`)
- Predict endpoint → API security: checks API key (evidence: `forecast_service/src/forecast_service/app/api/v1/endpoints/predict.py`)
- Predict endpoint → Prediction service: calls prediction (evidence: `forecast_service/src/forecast_service/app/api/v1/endpoints/predict.py`)
- Predict endpoint → Forecast request: accepts request (evidence: `forecast_service/src/forecast_service/app/api/v1/endpoints/predict.py`)
- Predict endpoint → Forecast response: returns response (evidence: `forecast_service/src/forecast_service/app/api/v1/endpoints/predict.py`)
- Prediction service → Forecast request: reads history (evidence: `forecast_service/src/forecast_service/app/services/predictor.py`)
- Prediction service → Forecast response: builds forecast (evidence: `forecast_service/src/forecast_service/app/services/predictor.py`)
- Prediction service → MLflow tracking: loads models (evidence: `forecast_service/src/forecast_service/app/services/predictor.py`)
- Energy forecaster → Feature engineering: transforms features (evidence: `forecast_service/src/forecast_service/model/forecaster.py`)
- Model training → Energy forecaster: fits and predicts (evidence: `forecast_service/src/forecast_service/model/trainer.py`)
- Model training → Model evaluation: evaluates folds (evidence: `forecast_service/src/forecast_service/model/trainer.py`)
- Hyperparameter tuning → Energy forecaster: uses models (evidence: `forecast_service/src/forecast_service/model/tuner.py`)
- Hyperparameter tuning → Model training: runs training (evidence: `forecast_service/src/forecast_service/model/tuner.py`)
- MLflow tracking → Energy forecaster: logs model (evidence: `forecast_service/src/forecast_service/tracking/mlflow_tracker.py`)
- MLflow tracking → MLflow registry: loads and registers (evidence: `forecast_service/src/forecast_service/tracking/mlflow_tracker.py`)
- Optimize endpoint → Optimization service: delegates optimization
- Optimization service → Optimization contracts: uses API schemas
- Optimization service → Solver factory: selects solver
- Solver factory → SciPy LP solver: creates solver (evidence: `optimizer_service/src/optimizer_service/solver/factory.py`)
- SciPy LP solver → Solver interface: implements interface (evidence: `optimizer_service/src/optimizer_service/solver/scipy_lp_solver.py`)
- SciPy LP solver → Load constraints: uses constraints (evidence: `optimizer_service/src/optimizer_service/solver/scipy_lp_solver.py`)
- SciPy LP solver → Schedule result: builds schedule (evidence: `optimizer_service/src/optimizer_service/solver/scipy_lp_solver.py`)
- SciPy LP solver → SciPy optimizer: solves LP (evidence: `optimizer_service/src/optimizer_service/solver/scipy_lp_solver.py`)
