# everest/libocpp architecture

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

- Interactive diagram: https://gitdiagram.com/everest/libocpp
- Repository: https://github.com/everest/libocpp

## Overview

##### Project type and purpose
- This is a C++ library (“libocpp”) that implements the Open Charge Point Protocol (OCPP) versions 1.6, 2.0.1 and in-progress 2.1.
- It is not a standalone server or web app but a client-side library to be embedded into EV charging station firmware. It handles websocket connections, message dispatching, state machines, database persistence, and functional blocks per OCPP spec.
- The README confirms that it is intended to integrate with charging station firmware (e.g., via EVerest) and exchange messages with a CSMS (Charge Station Management System).

##### File structure
- Top-level:
- `.ci/`, `run-docker(.sh)` and `Dockerfile` scripts for CI/CD and containerized builds/tests.
- `CMakeLists.txt` and `src/`, `lib/`, `include/` for source code.
- `config/` directories contain JSON schemas, SQL migrations and default configs per OCPP version.
- `src/code_generator/` contains Python scripts and Jinja templates that auto-generate message/enums/types C++ files.
- `include/ocpp/{common,v16,v2,v21}` and matching `lib/ocpp/...` implement protocol layers.
- `tests/` contains unit and integration tests for common code, versioned modules, database migrations, and config validations.
- Key patterns:
- Modular layering per OCPP version (common core, version-specific subdirectory).
- Code generation step that processes schema definitions into C++ message classes/enums.
- CMake build orchestrates code generation, compiling headers and libraries, running tests and packaging.

##### README for additional insights
- The README explains supported feature profiles, CSMS compatibility and integration guidelines.

##### Components
a. Main components
1. Client Firmware (your EVSE firmware)
2. libocpp library layers:
- Code Generator
- Common Core (websocket, dispatcher, queue, logging, utils)
- Version Modules: v1.6, v2.0.1, v2.1
- Functional Blocks & Profile Handlers (e.g., Smart Charging, Security, Transactions)
- Database Handler & Migrations (SQLite or embedded DB)
3. External CSMS (over websocket)
4. Configuration Store (JSON schemas, profile configs)
5. CI/CD Pipeline & Docker Build
b. Relationships and interactions
- Firmware → libocpp API calls to send/receive OCPP messages
- libocpp Common Core opens and manages a WebSocket connection to a CSMS endpoint
- Message Dispatcher routes incoming JSON messages to version‐appropriate handlers
- Handlers drive state machines, call into Functional Blocks, and persist data via Database Handler
- Configuration & profile schemas loaded at startup to validate and parameterize behavior
- Code Generator reads JSON schemas/templates → emits C++ header/source before build
- CI/CD orchestrates: run code generator → build with CMake → run unit tests → package Docker image
c. Architectural patterns / design principles
- Layered architecture: separation of concerns between core protocol, versioned logic and application firmware
- Dependency inversion: firmware depends on abstract libocpp interfaces; version modules implement those
- Code generation as a compile‐time plugin pattern: automated generation of message classes reduces boilerplate
- Use of migration scripts to evolve embedded database schema
- Modular CMake build, Dockerized CI for reproducibility
d. Key technologies / frameworks
- C++17 (or later), CMake
- Python + Jinja2 for code generation
- WebSocket library (libwebsockets) for transport
- SQLite (or pluggable storage) via library’s database handler
- Unit test frameworks (probably Catch2 or GTest)
- Docker for containerized builds

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "CI/CD & Docker Build"
        CI_Scripts["CI Scripts"]:::build
        GH["GitHub Actions"]:::build
        DockerFiles["Dockerfiles & Runners"]:::build
    end

    subgraph "Build & Code Generation"
        CG["Code Generator"]:::build
        CMake["CMake Build"]:::build
        Tests["Unit & Integration Tests"]:::build
        DockerPkg["Package Docker Image"]:::build
    end

    subgraph "Configuration Store"
        Config["Configuration Store"]:::config
    end

    subgraph "libocpp Runtime Library"
        Core["libocpp Core (WebSocket, Dispatcher, Queue)"]:::runtime
        WS["WebSocket Transport"]:::runtime
        Disp["Message Dispatcher"]:::runtime
        subgraph "Version Modules"
            V16["OCPP v1.6 Module"]:::runtime
            V2["OCPP v2.0.1 Module"]:::runtime
            V21["OCPP v2.1 Module"]:::runtime
        end
        FB["Functional Blocks"]:::runtime
        DB["Database Handler & Migrations"]:::runtime
    end

    Firmware["EVSE Firmware"]:::external
    CSMS["CSMS (WebSocket Server)"]:::external

    CI_Scripts -->|triggers| CG
    GH -->|triggers| CG
    DockerFiles -->|provides environment| CG
    CG -->|generates sources| CMake
    CMake -->|builds libraries| Core
    CMake -->|builds modules| V16
    CMake -->|builds modules| V2
    CMake -->|builds modules| V21
    CMake -->|builds| FB
    CMake -->|builds| DB
    CMake -->|runs| Tests
    Tests -->|on success| DockerPkg

    Firmware -->|calls libocpp API| Core
    Core -->|uses| WS
    WS -->|connects to| CSMS
    CSMS -->|sends JSON| WS
    WS -->|forwards messages| Disp
    Disp -->|routes to| V16
    Disp -->|routes to| V2
    Disp -->|routes to| V21
    V16 -->|invokes| FB
    V2 -->|invokes| FB
    V21 -->|invokes| FB
    FB -->|persists data| DB
    Config -->|loaded by| Core
    Config -->|loaded by| V16
    Config -->|loaded by| V2
    Config -->|loaded by| V21

    click CG "https://github.com/everest/libocpp/tree/main/src/code_generator"
    click Core "https://github.com/everest/libocpp/tree/main/include/ocpp/common"
    click WS "https://github.com/everest/libocpp/tree/main/include/ocpp/common/websocket"
    click Disp "https://github.com/everest/libocpp/blob/main/include/ocpp/common/message_dispatcher.hpp"
    click V16 "https://github.com/everest/libocpp/tree/main/include/ocpp/v16"
    click V2 "https://github.com/everest/libocpp/tree/main/include/ocpp/v2"
    click V21 "https://github.com/everest/libocpp/tree/main/include/ocpp/v21/messages"
    click FB "https://github.com/everest/libocpp/tree/main/include/ocpp/v2/functional_blocks"
    click DB "https://github.com/everest/libocpp/blob/main/include/ocpp/common/database/database_handler_common.hpp"
    click CI_Scripts "https://github.com/everest/libocpp/tree/main/.ci/build-kit"
    click GH "https://github.com/everest/libocpp/blob/main/.github/workflows/build_and_test.yaml"
    click DockerFiles "https://github.com/everest/libocpp/tree/main/Dockerfile"

    classDef runtime fill:#D0E8FF,stroke:#0366d6
    classDef build fill:#FFE8A1,stroke:#D97706
    classDef external fill:#D1FAD7,stroke:#15803D
    classDef config fill:#F0F0F0,stroke:#6B7280
```
