# chargepi/chargepi-go architecture

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

- Interactive diagram: https://gitdiagram.com/chargepi/chargepi-go
- Repository: https://github.com/chargepi/chargepi-go

## Overview

##### Project type and purpose
- ChargePi-go is a full-stack, modular EV charging point framework:
- Backend in Go (monolithic service with CLI, gRPC & HTTP APIs, hardware drivers, scheduler, smart-charging logic, persistence)
- Frontend UI in SvelteKit
- Docker‐based deployment and configuration management
- Hardware‐abstraction plugins (charge-point controllers, meters, displays, RFID readers)
- Purpose: unify disparate hardware into an OCPP 1.6/2.0.1-compliant charge point with API & UI for management, extensibility, and simulation.

##### File structure
- Top-level:
- cmd/ – CLI entry points: import, export, run, version
- internal/ – core application packages (api, auth, chargepoint, evse, diagnostics, sessions, smart‐charging, users)
- pkg/ – hardware drivers & utilities (display, indicator, power-meter, reader, observability)
- proto & gen/proto – protobuf definitions and generated gRPC code
- ui/ – frontend SvelteKit app
- deployments/docker – docker-compose for full stack
- scripts – environment setup, certificate generation
- main.go – application bootstrap
- build/Dockerfile – container image build
- Notice clean-architecture flavors:
- Adapters: internal/api/grpc, internal/api/http
- Domain & service layers: internal/chargepoint, sessions, smart-charging, users
- Infrastructure: internal/pkg/database (Badger), internal/pkg/settings, hardware plugins in pkg/

##### README insights
- Confirms modular, hardware-agnostic design
- Highlights OCPP protocol support (via internal/chargepoint and protobuf)
- Describes API, UI, simulator & demo modes
- Notes “framework” pattern – plugin‐style hardware drivers

a. Main components
- Frontend UI (SvelteKit)
- Backend service
– CLI layer (cmd/)
– API layer:
· HTTP server (internal/api/http, UI hosting, REST/JSON endpoints)
· gRPC server (internal/api/grpc)
– Domain services:
· Charge-point controller (internal/chargepoint)
· EVSE manager & device abstractions (internal/evse)
· Smart-charging scheduler (internal/smart-charging, internal/pkg/scheduler)
· Auth & session management (internal/auth, internal/sessions)
· User management (internal/users)
· Diagnostics (internal/diagnostics)
– Persistence:
· Settings & configuration manager (internal/pkg/settings)
· Database layer (internal/pkg/database, sessions & user Badger stores)
– Hardware plugins (pkg/display, pkg/reader, pkg/power-meter, pkg/indicator, pkg/evcc)
– Observability (pkg/observability)
- External systems
– OCPP Central System (over WebSocket/JSON via chargepoint module)
– Optional MQTT or other external integrations via API
b. Relationships & interactions
- UI ↔ HTTP API
- CLI ↔ domain services for import/export/configuration
- HTTP/gRPC API ↔ domain services
- Domain services ↔ hardware drivers via adapter interfaces
- Domain services ↔ persistence layer
- Charge-point ↔ external OCPP CS over network
c. Architectural patterns
- Clean/hexagonal architecture: clear separation of adapters (API, CLI), application logic (services), and infrastructure (database, drivers)
- Plugin architecture for hardware: loadable drivers under pkg/ and docs/contribution
- Event/scheduler pattern for smart-charging
d. Key technologies & frameworks
- Go modules, Go-Generate for protobuf (buf, protoc)
- gRPC + protobuf (proto/, gen/proto/)
- HTTP server (built-in net/http, SvelteKit for UI)
- Badger embedded KV store for sessions and users
- Docker & docker-compose for deployment
- SvelteKit, TailwindCSS for UI

##### Elements
- Labels
– UI, HTTP API, gRPC API, CLI, Domain Services, Persistence, Hardware Drivers, External OCPP CS
– UI → HTTP API → Domain Services → Drivers
– Domain Services ↔ DB
– Charge-point module → External OCPP CS

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend
    subgraph "Frontend"
        UI["Frontend UI (SvelteKit)"]:::frontend
    end

    %% Backend Adapters
    subgraph "Adapters"
        CLI["CLI Layer"]:::adapter
        HTTP["HTTP API Server"]:::adapter
        GRPC["gRPC API Server"]:::adapter
    end

    %% Domain Services
    subgraph "Domain Services"
        CP["Charge-Point Controller"]:::service
        EVSE["EVSE Manager & Abstractions"]:::service
        SC["Smart-Charging Scheduler"]:::service
        AUTH["Authentication Service"]:::service
        SESS["Session Management Service"]:::service
        USERS["User Management Service"]:::service
        DIAG["Diagnostics Service"]:::service
    end

    %% Infrastructure
    subgraph "Infrastructure"
        SETTINGS["Settings & Config Manager"]:::infra
        DB["Database Infrastructure"]:::infra
        OBS["Observability"]:::infra
        PROTO["Protobuf Definitions"]:::infra
        GENPROTO["Generated gRPC Code"]:::infra
        subgraph "Hardware Plugins"
            DISP["Display Drivers"]:::plugin
            READER["Reader Drivers"]:::plugin
            PM["Power-Meter Drivers"]:::plugin
            IND["Indicator Drivers"]:::plugin
            EVCC["EVCC Plugin"]:::plugin
        end
    end

    %% Deployment & Bootstrap
    MAIN["Application Bootstrap (main.go)"]:::infra
    DEPLOY["Deployment Config"]:::infra
    BUILD["Dockerfile"]:::infra

    %% External Systems
    OCPP["OCPP Central System"]:::external

    %% Connections
    UI -->|uses REST| HTTP
    CLI -->|invokes| CP
    CLI -->|invokes| EVSE
    CLI -->|invokes| SC
    HTTP -->|calls| CP
    HTTP -->|calls| EVSE
    HTTP -->|calls| SC
    HTTP -->|auth| AUTH
    HTTP -->|sessions| SESS
    HTTP -->|users| USERS
    HTTP -->|diagnostics| DIAG
    GRPC -->|calls| CP
    GRPC -->|calls| EVSE
    GRPC -->|calls| SC
    GRPC -->|auth| AUTH
    GRPC -->|sessions| SESS
    GRPC -->|users| USERS
    GRPC -->|diagnostics| DIAG

    %% Domain to Infra
    CP -->|stores config| SETTINGS
    AUTH -->|stores| DB
    SESS -->|stores| DB
    USERS -->|stores| DB
    DIAG -->|logs| OBS
    SC -->|schedules| SETTINGS

    %% Domain to Plugins
    CP -->|controls| DISP
    CP -->|reads| READER
    CP -->|measures| PM
    CP -->|indicates| IND
    CP -->|integrates| EVCC

    %% Charge-Point to External
    CP -->|OCPP over WS| OCPP

    %% Bootstrap and Deployment
    MAIN -->|initializes| SETTINGS
    MAIN -->|loads plugins| DISP
    MAIN -->|loads plugins| READER
    MAIN -->|loads plugins| PM
    MAIN -->|loads plugins| IND
    MAIN -->|loads plugins| EVCC
    MAIN -->|starts adapters| HTTP
    MAIN -->|starts adapters| GRPC
    MAIN -->|starts adapters| CLI

    DEPLOY --- BUILD
    MAIN --- DEPLOY

    %% Click Events
    click UI "https://github.com/chargepi/chargepi-go/tree/v2/ui/"
    click CLI "https://github.com/chargepi/chargepi-go/tree/v2/cmd/"
    click HTTP "https://github.com/chargepi/chargepi-go/blob/v2/internal/api/http/application.go"
    click GRPC "https://github.com/chargepi/chargepi-go/blob/v2/internal/api/grpc/server.go"
    click CP "https://github.com/chargepi/chargepi-go/tree/v2/internal/chargepoint/"
    click EVSE "https://github.com/chargepi/chargepi-go/tree/v2/internal/evse/"
    click SC "https://github.com/chargepi/chargepi-go/blob/v2/internal/smart-charging/manager.go"
    click AUTH "https://github.com/chargepi/chargepi-go/blob/v2/internal/auth/manager.go"
    click SESS "https://github.com/chargepi/chargepi-go/blob/v2/internal/sessions/pkg/database/session-badger.go"
    click USERS "https://github.com/chargepi/chargepi-go/blob/v2/internal/users/pkg/database/badger.go"
    click DIAG "https://github.com/chargepi/chargepi-go/blob/v2/internal/diagnostics/manager.go"
    click SETTINGS "https://github.com/chargepi/chargepi-go/blob/v2/internal/pkg/settings/manager.go"
    click DB "https://github.com/chargepi/chargepi-go/blob/v2/internal/pkg/database/database.go"
    click DISP "https://github.com/chargepi/chargepi-go/tree/v2/pkg/display/"
    click READER "https://github.com/chargepi/chargepi-go/tree/v2/pkg/reader/"
    click PM "https://github.com/chargepi/chargepi-go/tree/v2/pkg/power-meter/"
    click IND "https://github.com/chargepi/chargepi-go/tree/v2/pkg/indicator/"
    click EVCC "https://github.com/chargepi/chargepi-go/tree/v2/pkg/evcc/"
    click OBS "https://github.com/chargepi/chargepi-go/blob/v2/pkg/observability/logging/logging.go"
    click PROTO "https://github.com/chargepi/chargepi-go/tree/v2/proto/"
    click GENPROTO "https://github.com/chargepi/chargepi-go/tree/v2/gen/proto/"
    click MAIN "https://github.com/chargepi/chargepi-go/blob/v2/main.go"
    click DEPLOY "https://github.com/chargepi/chargepi-go/blob/v2/deployments/docker/docker-compose.yaml"
    click BUILD "https://github.com/chargepi/chargepi-go/tree/v2/build/Dockerfile"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:1px;
    classDef adapter fill:#bbf,stroke:#333,stroke-width:1px;
    classDef service fill:#bfb,stroke:#333,stroke-width:1px;
    classDef infra fill:#ffb,stroke:#333,stroke-width:1px;
    classDef plugin fill:#fbb,stroke:#333,stroke-width:1px;
    classDef external fill:#fff,stroke:#666,stroke-dasharray: 5 5;
```
