# ecog-io/iso15118 architecture

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

## Overview

- The EVCC (Electric Vehicle Communication Controller) – implemented under the iso15118/evcc directory.
- The SECC (Supply Equipment Communication Controller) – implemented under the iso15118/secc directory.
There is also a large “shared” library (under iso15118/shared) that includes common functionalities such as messaging (protocol definitions, schemas, state machines), certificate management (PKI files, certificate generation scripts), logging, and utilities. This clearly indicates that the project is structured to handle two interacting controllers that simulate or drive real-world ISO 15118 communications.

##### Key components
a. EVCC Component:
- Configuration interaction via settings (evcc_settings.py, evcc_config.py) and different state implementations (DINSPEC, ISO15118-2, ISO15118-20, SAP states).
b. SECC Component:
c. Shared Library:
d. External Environment:
- Docker and Deployment: Represent Docker containers (Docker Compose setups like docker-compose.yml, docker-compose-dev.yml, docker-compose-prod.yml, and the host-mode configuration) that orchestrate the running of both EVCC and SECC.
- Environment Variables & Configuration Files: Show the role of several .env files (for Docker and local development) and the Makefile that ties together build, installation, and launch commands.
e. Testing and CI/CD:

##### Relationships and data flow
- Both controllers to the shared library to denote the usage of common message encoding/decoding, data types, and protocol definitions.
- From an infrastructure perspective, show that both EVCC and SECC are deployed in containerized environments. Optionally indicate that containers can run in “host mode” on Linux to properly handle the IPv6 link-local addresses required by ISO 15118.
- That configuration and certificate management modules affect both controllers (using environment settings and the PKI directory).

##### Architectural patterns and design principles
- Separation of concerns: Notice the distinct roles of EVCC, SECC, and shared libraries.
- Modularity / extensibility: The use of individual directories for different protocol states and the component separation for message schemas indicate a plug-in style design.
- Communication Over Sockets: TCP/UDP clients and servers are used to emulate or run the ISO 15118 communication flow.
- Container-based deployment: Using Docker-compose for both development and production environments.
- Use of environment variable based configuration which tailors the behavior of the controllers (as seen with the various ENV files).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "EVCC Module"
        EVCC_Main("main.py"):::evcc
        EVCC_Config1("evcc_config.py"):::evcc
        EVCC_Config2("evcc_settings.py"):::evcc
        EVCC_States("State Machines"):::evcc
        EVCC_TCP("TCP Client"):::evcc
        EVCC_UDP("UDP Client"):::evcc
    end

    subgraph "SECC Module"
        SECC_Main("main.py"):::secc
        SECC_Settings("secc_settings.py"):::secc
        SECC_States("State Machines"):::secc
        SECC_TCP("TCP Server"):::secc
        SECC_UDP("UDP Server"):::secc
    end

    subgraph "Shared Library"
        Shared_Messages("Messaging Definitions"):::shared
        Shared_PKI("PKI Management"):::shared
        Shared_Logging("Logging Configuration"):::shared
        Shared_Utils("Utilities & Common Code"):::shared
    end

    subgraph "Deployment & Environment"
        Docker("Docker Compose Files"):::deployment
        EnvFiles("Environment Variables"):::deployment
        BuildMgmt("Makefile & Deployment"):::deployment
    end

    subgraph "Testing & CI/CD"
        Tests("Tests"):::testing
        CICD("CI/CD Workflows"):::testing
    end

    %% Internal EVCC dependencies
    EVCC_Main -->|"loads"| EVCC_Config1
    EVCC_Main -->|"loads"| EVCC_Config2
    EVCC_Main -->|"initiates"| EVCC_States
    EVCC_Main -->|"initiates"| EVCC_TCP
    EVCC_Main -->|"initiates"| EVCC_UDP

    %% Internal SECC dependencies
    SECC_Main -->|"loads"| SECC_Settings
    SECC_Main -->|"initiates"| SECC_States
    SECC_Main -->|"initiates"| SECC_TCP
    SECC_Main -->|"initiates"| SECC_UDP

    %% Communication between EVCC and SECC
    EVCC_TCP -->|"TCP_conn"| SECC_TCP
    EVCC_UDP -->|"UDP_conn"| SECC_UDP

    %% Both controllers use shared functionalities
    EVCC_States -->|"uses"| Shared_Messages
    SECC_States -->|"uses"| Shared_Messages
    EVCC_Main ---|"utilizes"| Shared_Utils
    SECC_Main ---|"utilizes"| Shared_Utils
    EVCC_Main ---|"integrates"| Shared_PKI
    SECC_Main ---|"integrates"| Shared_PKI
    EVCC_Main ---|"logs via"| Shared_Logging
    SECC_Main ---|"logs via"| Shared_Logging

    %% Deployment relationships
    Docker --->|"deploys"| EVCC_Main
    Docker --->|"deploys"| SECC_Main
    EnvFiles --->|"configures"| EVCC_Config1
    EnvFiles --->|"configures"| EVCC_Config2
    EnvFiles --->|"configures"| SECC_Settings
    BuildMgmt --->|"builds"| EVCC_Main
    BuildMgmt --->|"builds"| SECC_Main

    %% Testing and CI/CD triggers
    Tests ---|"validates"| EVCC_Main
    Tests ---|"validates"| SECC_Main
    Tests ---|"validates"| Shared_Messages
    CICD ---|"automates"| EVCC_Main
    CICD ---|"automates"| SECC_Main

    %% Click Events for EVCC
    click EVCC_Main "https://github.com/ecog-io/iso15118/blob/master/iso15118/evcc/main.py"
    click EVCC_Config1 "https://github.com/ecog-io/iso15118/blob/master/iso15118/evcc/evcc_config.py"
    click EVCC_Config2 "https://github.com/ecog-io/iso15118/blob/master/iso15118/evcc/evcc_settings.py"
    click EVCC_States "https://github.com/ecog-io/iso15118/tree/master/iso15118/evcc/states/"
    click EVCC_TCP "https://github.com/ecog-io/iso15118/blob/master/iso15118/evcc/transport/tcp_client.py"
    click EVCC_UDP "https://github.com/ecog-io/iso15118/blob/master/iso15118/evcc/transport/udp_client.py"

    %% Click Events for SECC
    click SECC_Main "https://github.com/ecog-io/iso15118/blob/master/iso15118/secc/main.py"
    click SECC_Settings "https://github.com/ecog-io/iso15118/blob/master/iso15118/secc/secc_settings.py"
    click SECC_States "https://github.com/ecog-io/iso15118/tree/master/iso15118/secc/states/"
    click SECC_TCP "https://github.com/ecog-io/iso15118/blob/master/iso15118/secc/transport/tcp_server.py"
    click SECC_UDP "https://github.com/ecog-io/iso15118/blob/master/iso15118/secc/transport/udp_server.py"

    %% Click Events for Shared Library
    click Shared_Messages "https://github.com/ecog-io/iso15118/tree/master/iso15118/shared/messages/"
    click Shared_PKI "https://github.com/ecog-io/iso15118/tree/master/iso15118/shared/pki/"
    click Shared_Logging "https://github.com/ecog-io/iso15118/tree/master/iso15118/shared/logging/"
    click Shared_Utils "https://github.com/ecog-io/iso15118/tree/master/iso15118/shared/"

    %% Click Events for Deployment & Environment
    click Docker "https://github.com/ecog-io/iso15118/blob/master/docker-compose.yml"
    click EnvFiles "https://github.com/ecog-io/iso15118/blob/master/.env.dev.docker"
    click BuildMgmt "https://github.com/ecog-io/iso15118/tree/master/Makefile"

    %% Click Events for Testing & CI/CD
    click Tests "https://github.com/ecog-io/iso15118/tree/master/tests/"
    click CICD "https://github.com/ecog-io/iso15118/tree/master/.github/"

    %% Styles
    classDef evcc fill:#f4a582,stroke:#d95f02,stroke-width:2px;
    classDef secc fill:#92c5de,stroke:#0571b0,stroke-width:2px;
    classDef shared fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef deployment fill:#ff7f00,stroke:#e31a1c,stroke-width:2px;
    classDef testing fill:#cab2d6,stroke:#6a3d9a,stroke-width:2px;
```
