# motown-io/motown architecture

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

- Interactive diagram: https://gitdiagram.com/motown-io/motown
- Repository: https://github.com/motown-io/motown

## Overview

##### Project type and purpose
- motown is a modular, Java-based, event-driven platform for integrating EV charging infrastructure.
- It is organized as a collection of modules (services and libraries) that communicate via commands and events on a message bus (using Axon).

##### Key architectural layers & modules
- Domain Core
– domain/core-api: shared command and event definitions (POJOs).
– domain/command-handling, domain/command-authorization: command handlers and authorization logic.
– domain/utils: shared utilities for correlation, interceptors, event gateways.
- Application Services
– chargingstation-configuration, identification-authorization, incoming-datatransfer, selective-authorization, etc.
– Each has an “app” submodule (command side, Spring-Axon handlers) and a “view-model” submodule (event listeners, Spring REST/DB).
- Operator API
– operator-api/json: JSON-over-HTTP REST API (Jersey) exposing commands.
– operator-api/view-model: event listeners projecting into a HSQLDB view.
- Protocol adapters / external connectors
– ocpp/v12-soap, ocpp/v15-soap: SOAP endpoints for OCPP.
– ocpp/websocket-json: WebSocket JSON endpoint for OCPP v15.
– mobi-europe/source & destination: SOAP and REST adapters for e-mobility roaming.
– ocpi/ocpi-identification-authorization-plugin: plugin implementing OCPI auth.
– vas/v10-soap & vas/view-model: Value-Added Services SOAP publisher/subscriber.
- Samples & Configuration
– samples/*: “reference architecture” Spring boot deployments, simple and distributed.
– configuration plugins illustrate how to compose modules in a container.

##### How commands and events flow
- A REST/JSON or SOAP/WebSocket request arrives at a protocol adapter (operator-api, ocpp, mobi-europe, ocpi, vas).
- The adapter translates to a Domain Command and sends it to the CommandGateway (Axon).
- Domain/command-handling and domain/command-authorization consume the command, apply business logic, emit Domain Events.
- Events are published on the message bus.
- View-model modules (per service) listen for events, update their own persistence (HSQLDB), and expose read models (REST or JAX-RS).

##### Detail level
– Capture all major modules (operator-api, chargingstation-configuration, identification-authorization, mobi-europe, ocpp, ocpi, vas).
– Show shared libraries only once, annotate which modules depend on them.
– Do not clutter with every sub-package—focus on submodule level and communication channels.
– Annotate key Spring/Axon components: CommandGateway, EventHandlers, Repositories.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Clients["Clients"]:::external

    %% Protocol Adapters
    subgraph "Protocol Adapters"
        direction TB
        OP_JSON["operator-api/json (REST/JSON)"]:::protocol
        OCPP_V12["ocpp/v12-soap (SOAP v1.2)"]:::protocol
        OCPP_V15_SOAP["ocpp/v15-soap (SOAP v1.5)"]:::protocol
        OCPP_WS["ocpp/websocket-json (WebSocket JSON)"]:::protocol
        OCPI_PLUGIN["ocpi/ocpi-identification-authorization-plugin"]:::protocol
        MOBI_SRC["mobi-europe/source (SOAP)"]:::protocol
        MOBI_DST["mobi-europe/destination (REST)"]:::protocol
        VAS_SOAP["vas/v10-soap (SOAP)"]:::protocol
    end

    %% Command Bus
    Clients --> OP_JSON
    Clients --> OCPP_V12
    Clients --> OCPP_V15_SOAP
    Clients --> OCPP_WS
    Clients --> OCPI_PLUGIN
    Clients --> MOBI_SRC
    Clients --> MOBI_DST
    Clients --> VAS_SOAP

    subgraph "Command & Domain Core"
        direction TB
        CMD_BUS["CommandBus (Axon)"]:::command
        subgraph "Application Services"
            direction TB
            CCS_APP["chargingstation-configuration/app"]:::command
            IA_APP["identification-authorization/app"]:::command
        end
        subgraph "Domain Core Modules"
            direction TB
            CMD_HANDLING["domain/command-handling"]:::command
            CMD_AUTH["domain/command-authorization"]:::command
        end
        subgraph "Shared Libraries"
            direction TB
            CORE_API["domain/core-api"]:::library
            DOM_UTILS["domain/utils"]:::library
        end
    end

    OP_JSON -->|"/commands"| CMD_BUS
    OCPP_V12 -->|"/commands"| CMD_BUS
    OCPP_V15_SOAP -->|"/commands"| CMD_BUS
    OCPP_WS -->|"/commands"| CMD_BUS
    OCPI_PLUGIN -->|"/commands"| CMD_BUS
    MOBI_SRC -->|"/commands"| CMD_BUS
    MOBI_DST -->|"/commands"| CMD_BUS
    VAS_SOAP -->|"/commands"| CMD_BUS

    CMD_BUS --> CCS_APP
    CMD_BUS --> IA_APP
    CMD_BUS --> CMD_HANDLING
    CMD_BUS --> CMD_AUTH

    CORE_API --> CMD_HANDLING
    CORE_API --> CMD_AUTH
    DOM_UTILS --> CMD_HANDLING
    DOM_UTILS --> CMD_AUTH

    %% Event Bus
    CMD_HANDLING --> EVENT_BUS
    CMD_AUTH --> EVENT_BUS
    CCS_APP --> EVENT_BUS
    IA_APP --> EVENT_BUS

    EVENT_BUS["EventBus (Axon)"]:::eventbus

    %% View-Model & Datastores
    subgraph "View-Model & Read Side"
        direction TB
        CCS_VIEW["chargingstation-configuration/view-model"]:::view
        IA_SELECT["identification-authorization/selective-authorization-service"]:::view
        OP_VIEW["operator-api/view-model"]:::view
        VAS_VIEW["vas/view-model"]:::view
        subgraph "Datastores (HSQLDB)"
            direction TB
            DB_CCS["HSQLDB (CCS)"]:::db
            DB_IA["HSQLDB (Selective Auth)"]:::db
            DB_OP["HSQLDB (Operator API)"]:::db
            DB_VAS["HSQLDB (VAS)"]:::db
        end
    end

    EVENT_BUS --> CCS_VIEW
    EVENT_BUS --> IA_SELECT
    EVENT_BUS --> OP_VIEW
    EVENT_BUS --> VAS_VIEW

    CCS_VIEW --> DB_CCS
    IA_SELECT --> DB_IA
    OP_VIEW --> DB_OP
    VAS_VIEW --> DB_VAS

    %% Shared Utilities
    subgraph "Shared Utilities"
        direction TB
        UTIL_REST["utils/rest"]:::library
        UTIL_SOAP["utils/soap"]:::library
        MOBI_SHARED["mobi-europe/shared"]:::library
    end

    %% Samples & Configurations
    subgraph "Samples & Configurations"
        direction TB
        SAMPLE_SIMPLE["samples/configuration-simple"]:::sample
        SAMPLE_DIST["samples/configuration-distributed"]:::sample
        SAMPLE_INCOMING["samples/incoming-datatransfer-handling"]:::sample
        SAMPLE_AUTH["samples/authentication"]:::sample
    end

    %% Click Events
    click CORE_API "https://github.com/motown-io/motown/tree/develop/domain/core-api"
    click CMD_HANDLING "https://github.com/motown-io/motown/tree/develop/domain/command-handling"
    click CMD_AUTH "https://github.com/motown-io/motown/tree/develop/domain/command-authorization"
    click DOM_UTILS "https://github.com/motown-io/motown/tree/develop/domain/utils"
    click CCS_APP "https://github.com/motown-io/motown/tree/develop/chargingstation-configuration/app"
    click CCS_VIEW "https://github.com/motown-io/motown/tree/develop/chargingstation-configuration/view-model"
    click IA_APP "https://github.com/motown-io/motown/tree/develop/identification-authorization/app"
    click IA_SELECT "https://github.com/motown-io/motown/tree/develop/identification-authorization/selective-authorization-service"
    click OP_JSON "https://github.com/motown-io/motown/tree/develop/operator-api/json"
    click OP_VIEW "https://github.com/motown-io/motown/tree/develop/operator-api/view-model"
    click OCPP_V12 "https://github.com/motown-io/motown/tree/develop/ocpp/v12-soap"
    click OCPP_V15_SOAP "https://github.com/motown-io/motown/tree/develop/ocpp/v15-soap"
    click OCPP_WS "https://github.com/motown-io/motown/tree/develop/ocpp/websocket-json"
    click OCPI_PLUGIN "https://github.com/motown-io/motown/tree/develop/ocpi/ocpi-identification-authorization-plugin"
    click MOBI_SRC "https://github.com/motown-io/motown/tree/develop/mobi-europe/source"
    click MOBI_DST "https://github.com/motown-io/motown/tree/develop/mobi-europe/destination"
    click MOBI_SHARED "https://github.com/motown-io/motown/tree/develop/mobi-europe/shared"
    click VAS_SOAP "https://github.com/motown-io/motown/tree/develop/vas/v10-soap"
    click VAS_VIEW "https://github.com/motown-io/motown/tree/develop/vas/view-model"
    click UTIL_REST "https://github.com/motown-io/motown/tree/develop/utils/rest"
    click UTIL_SOAP "https://github.com/motown-io/motown/tree/develop/utils/soap"
    click SAMPLE_SIMPLE "https://github.com/motown-io/motown/tree/develop/samples/configuration-simple"
    click SAMPLE_DIST "https://github.com/motown-io/motown/tree/develop/samples/configuration-distributed"
    click SAMPLE_INCOMING "https://github.com/motown-io/motown/tree/develop/samples/incoming-datatransfer-handling"
    click SAMPLE_AUTH "https://github.com/motown-io/motown/tree/develop/samples/authentication"

    %% Styles
    classDef protocol fill:#ADD8E6,stroke:#000
    classDef command fill:#90EE90,stroke:#000
    classDef eventbus fill:#FFA500,stroke:#000
    classDef view fill:#FFFF99,stroke:#000
    classDef db fill:#FFFF99,stroke:#000,shape:cylinder
    classDef library fill:#D3D3D3,stroke:#000,stroke-dasharray: 5 5
    classDef sample fill:#E6E6FA,stroke:#000
    classDef external fill:#FFFFFF,stroke:#000,stroke-dasharray: 2 2,shape:rectangular
```
