# akkudoktor-eos/eos architecture

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

- Interactive diagram: https://gitdiagram.com/akkudoktor-eos/eos
- Repository: https://github.com/akkudoktor-eos/eos

## Overview

##### Main Components
- Energy System Simulator/Optimizer (EMS): At the core, this application models and optimizes an energy system. Components include Battery, PVForecast, Load, Heatpump, and more. These elements can be represented as distinct modules.
- Forecasting & Prediction Modules: Include subcomponents such as PVForecast, Load Prediction, Electricity Price forecasting (Strompreis), and weather integrations.
- Devices/Subsystems: Clearly call out modules representing physical devices (battery, heat pump, inverter, etc.).
- Configuration Management: Highlight the configuration system that manages settings via JSON configuration files (EOS.config.json and default.config.json) and environment variables.
- API Server: Indicated by the presence of src/akkudoktoreos/server (e.g., eos.py, eosdash.py), which provides endpoints for external interaction and documentation via Swagger.
- Data Handling: Represent the modules handling measurement data, configuration loadings, and data caching (also depicted under “data” and “utils” modules).
- Optimization Engine: The optimization folder contains genetic algorithms and optimization classes that drive smart decision-making.
- External Interfaces & Deployment: Note the Dockerfile, docker-compose.yaml, and CI/CD configurations indicating deployment containers along with GitHub workflows.

##### Relationships and Interactions
- The API server (src/akkudoktoreos/server) handles incoming requests from clients (with interactive documentation at http://localhost:8503/docs) and passes these to the core EMS component.
- The EMS orchestrates simulation and optimization by invoking the various device modules (battery, heat pump, inverter) and forecasting modules (PVForecast, weather, load).
- Configuration components read and possibly update settings from the JSON config files; these settings are then used by the EMS and other modules to run simulations/optimizations.
- Data flows can be visualized from input data (loaded from files or API) to prediction modules to the optimization engine, then finally to generation of simulation results (which may be visualized or returned via API).

##### Architectural Patterns and Design Principles
- The project appears to follow a modular and layered architecture. Modules are separated by functionality (config, core, prediction, optimization, server) which is helpful to decouple concerns.
- Abstraction is utilized with “abc” (abstract base classes) in multiple components (configabc, coreabc, devicesabc, etc.) to enforce interfaces and enable customization or future extension.
- Dependency injection and configuration management are emphasized via the config files, enabling both default and custom operation flows.
- Testing is treated as first-class (see tests directory), ensuring that individual modules can be verified independently.
- The OpenAPI / Swagger integration demonstrates an API-first design for external connectivity.

##### Instructing the Principal Software Engineer
- Elements are clearly labeled. For instance, the “Battery” module should clearly mention its associated methods related to state of charge and losses.
- API calls enter through the Server component.
- The EMS distributes tasks to Forecast and Optimization modules.
- Data flows back from modules to the API layer for output generation.
- External integrations (Swagger API docs, Docker container orchestration) to underline deployment and connectivity aspects.

##### Detailed Component List
- API Server:
- Components: eos.py, eosdash.py, server.py.
- Role: Exposing API endpoints, integrating Swagger documentation.
- Energy Management System (EMS):
- Modules: core/ems, optimization (genetic algorithms, optimization logic), and coordination between device components.
- Forecast and Prediction Modules:
- Components: pvforecast, elecprice, load, weather.
- Role: Predicting generation, demand, and pricing.
- Device Modules:
- Components: battery, inverter, heatpump, generic device interfaces.
- Configuration & Data Management:
- Components: config directory, default.config.json, dynamic updating of EOS.config.json.
- Utility Services:
- Components: cache, datetime utilities, logging.
- Infrastructure & Deployment:
- Dockerfile, docker-compose.yaml, CI/CD workflow indicators from .github and Makefile.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        API_Server["API Server"]:::api
        API_Eos["eos.py"]:::api
        API_EosDash["eosdash.py"]:::api
        API_ServerPy["server.py"]:::api
        API_Server --> API_Eos
        API_Server --> API_EosDash
        API_Server --> API_ServerPy
    end

    %% Business & Application Layer
    subgraph "Business & Application Layer"
        EMS_Core["EMS Core"]:::core

        %% Forecast & Prediction Modules
        subgraph "Forecast & Prediction Modules"
            PV_Forecast["PV Forecast"]:::prediction
            Load_Prediction["Load Prediction"]:::prediction
            ElecPrice_Forecast["Electricity Price Forecast"]:::prediction
            Weather_Integration["Weather Integration"]:::prediction
        end

        %% Device Modules
        subgraph "Device Modules"
            Battery_Module["Battery Module"]:::device
            HeatPump_Module["Heat Pump Module"]:::device
            Inverter_Module["Inverter Module"]:::device
            Generic_Device["Generic Device Interfaces"]:::device
        end

        %% Optimization Engine
        subgraph "Optimization Engine"
            Optimization_Logic["Optimization Logic"]:::optimization
            Genetic_Algo["Genetic Algorithms"]:::optimization
            Optimization_Logic --> Genetic_Algo
        end

        EMS_Core -->|"calls"| PV_Forecast
        EMS_Core -->|"calls"| Load_Prediction
        EMS_Core -->|"calls"| ElecPrice_Forecast
        EMS_Core -->|"calls"| Weather_Integration

        EMS_Core -->|"controls"| Battery_Module
        EMS_Core -->|"controls"| HeatPump_Module
        EMS_Core -->|"controls"| Inverter_Module
        EMS_Core -->|"controls"| Generic_Device

        EMS_Core -->|"optimizes with"| Optimization_Logic
    end

    %% Data and Configuration Layer
    subgraph "Data and Configuration Layer"
        Config_Manager["Config Manager"]:::config
        Default_Config["Default Configuration"]:::config
        Measurement_Data["Measurement Data Handling"]:::utility
        Utilities["Utilities (Cache, DateTime, Logging)"]:::utility
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        Docker_Config["Docker Config"]:::external
        CICD_Pipelines["CI/CD Pipelines"]:::external
    end

    %% Connections between layers
    API_Server -->|"API call"| EMS_Core
    Config_Manager -->|"configures"| EMS_Core
    Measurement_Data -->|"feeds data"| EMS_Core
    Utilities -->|"supports"| EMS_Core
    Docker_Config -->|"deploys"| API_Server
    CICD_Pipelines -->|"integrates"| API_Server

    %% Click Events
    click EMS_Core "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/core/ems.py"
    click PV_Forecast "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/prediction/pvforecast.py"
    click Load_Prediction "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/prediction/load.py"
    click ElecPrice_Forecast "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/prediction/elecprice.py"
    click Weather_Integration "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/prediction/weather.py"
    click Battery_Module "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/devices/battery.py"
    click HeatPump_Module "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/devices/heatpump.py"
    click Inverter_Module "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/devices/inverter.py"
    click Generic_Device "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/devices/generic.py"
    click Config_Manager "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/config/config.py"
    click Default_Config "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/data/default.config.json"
    click API_Eos "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/server/eos.py"
    click API_EosDash "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/server/eosdash.py"
    click API_ServerPy "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/server/server.py"
    click Measurement_Data "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/measurement/measurement.py"
    click Utilities "https://github.com/akkudoktor-eos/eos/tree/main/src/akkudoktoreos/utils/"
    click Optimization_Logic "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/optimization/optimization.py"
    click Genetic_Algo "https://github.com/akkudoktor-eos/eos/blob/main/src/akkudoktoreos/optimization/genetic.py"
    click Docker_Config "https://github.com/akkudoktor-eos/eos/tree/main/Dockerfile"
    click CICD_Pipelines "https://github.com/akkudoktor-eos/eos/tree/main/.github/"

    %% Styles
    classDef api fill:#F8B195,stroke:#333,stroke-width:2px,color:#000,stroke-dasharray: 5 5;
    classDef core fill:#C06C84,stroke:#333,stroke-width:2px,color:#FFF;
    classDef prediction fill:#355C7D,stroke:#333,stroke-width:2px,color:#FFF;
    classDef device fill:#6C5B7B,stroke:#333,stroke-width:2px,color:#FFF;
    classDef config fill:#99B898,stroke:#333,stroke-width:2px,color:#000;
    classDef optimization fill:#F67280,stroke:#333,stroke-width:2px,color:#FFF;
    classDef external fill:#F8E9A1,stroke:#333,stroke-width:2px,color:#000;
    classDef utility fill:#E84A5F,stroke:#333,stroke-width:2px,color:#FFF;
```
