# citrineos/citrineos-core architecture

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

- Interactive diagram: https://gitdiagram.com/citrineos/citrineos-core
- Repository: https://github.com/citrineos/citrineos-core

## Overview

##### Project Type and Purpose
- CitrineOS is an open‐source modular server runtime for managing electric vehicle (EV) charging infrastructure.
- It acts as a central hub for handling OCPP 2.0.1 messages, dynamic schema validation, module-based business logic, and integration with external services such as message brokers and a PostgreSQL database.
- The project supports a full-stack backend with evolving modules (e.g., Certificates, Configuration, EVDriver, Monitoring, OcppRouter, Reporting, SmartCharging, Tenant, Transactions) along with supportive utilities and data layers.

##### File Structure – Key Components
- 00_Base: This directory holds the core functionalities such as OCPP message routing, API definitions, configuration handling, schema processing, and all the low-level interfaces (e.g., routers, message endpoints, cache interfaces). It forms the heart of the server’s communication and business event handling.
- 01_Data: Dedicated to data models and persistence. It contains Sequelize models and repository patterns to interact with a PostgreSQL database.
- 02_Util: Contains shared utilities like authorization, caching (in-memory and Redis), certificate utilities (ACME, Hubject), file access components (FTP, S3), and queue integrations (RabbitMQ, Google PubSub, Kafka). These support external integrations and facilitate cross-cutting concerns.
- 03_Modules: Encapsulates the different modular service components, each representing a business capability. Each module (e.g., Certificates, Configuration, EVDriver, Monitoring, etc.) defines its API via decorators (@AsHandler, @AsMessageEndpoint, @AsDataEndpoint) and has its own set of tests and configuration files.
- Server and Swarm: These directories provide the deployment and runtime orchestration aspects, including Docker (Dockerfiles, docker-compose.yml), environment configurations, and deployment scripts. They also define the external services (RabbitMQ, PostgreSQL, Directus) and expose endpoints (swagger, websocket servers).

##### Key Architectural Patterns and Technologies
- Modularity: The project is built as a series of independent modules, each self-contained and following similar interface and API patterns.
- Layered Architecture: There is a clear separation between the core runtime (00_Base), data persistence (01_Data), utilities (02_Util), and higher-level business modules (03_Modules).
- Messaging and Integration: Dynamic OCPP message handling is supported with schema validation via AJV; messaging endpoints and queue integrations (RabbitMQ/Google PubSub) are abstracted in utilities.
- Deployment via Containers: Both the Server and Swarm directories include docker-compose configurations to orchestrate the environment (with RabbitMQ, PostgreSQL, Directus, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Interfaces"
        ES["Charging Stations"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        API["API & WebSocket Endpoints"]:::api
    end

    %% Core Runtime
    subgraph "Core Services"
        CORE["00_Base – Core Services"]:::core
    end

    %% Data Persistence Layer
    subgraph "Data Persistence Layer"
        DATA["01_Data – Persistence Layer"]:::database
    end

    %% Shared Utilities
    subgraph "Shared Utilities"
        UTIL["02_Util – Utilities & Integrations"]:::util
    end

    %% Business Modules
    subgraph "Business Modules"
        MOD_CERT["Certificates Module"]:::moduleDetail
        MOD_CONF["Configuration Module"]:::moduleDetail
        MOD_EVD["EVDriver Module"]:::moduleDetail
        MOD_MON["Monitoring Module"]:::moduleDetail
        MOD_ORC["OcppRouter Module"]:::moduleDetail
        MOD_REP["Reporting Module"]:::moduleDetail
        MOD_SC["SmartCharging Module"]:::moduleDetail
        MOD_TEN["Tenant Module"]:::moduleDetail
        MOD_TRA["Transactions Module"]:::moduleDetail
    end

    %% Deployment & Orchestration
    subgraph "Deployment & Orchestration"
        DEP["Deployment & Orchestration"]:::deployment
    end

    %% External Services
    subgraph "External Services"
        RMQ["RabbitMQ"]:::externalService
        PG["PostgreSQL"]:::externalService
        DIR["Directus"]:::externalService
    end

    %% Connections between layers
    ES -->|"connects"| API
    API -->|"for message routing"| CORE
    CORE -->|"persist state"| DATA
    CORE -->|"invokes utilities"| UTIL

    %% Core to Modules (dispatching business logic)
    CORE -->|"dispatches"| MOD_CERT
    CORE -->|"dispatches"| MOD_CONF
    CORE -->|"dispatches"| MOD_EVD
    CORE -->|"dispatches"| MOD_MON
    CORE -->|"dispatches"| MOD_ORC
    CORE -->|"dispatches"| MOD_REP
    CORE -->|"dispatches"| MOD_SC
    CORE -->|"dispatches"| MOD_TEN
    CORE -->|"dispatches"| MOD_TRA

    %% Utilities support both Core and Modules
    UTIL -->|"supports"| CORE
    UTIL -->|"supports"| MOD_CERT
    UTIL -->|"supports"| MOD_CONF
    UTIL -->|"supports"| MOD_EVD
    UTIL -->|"supports"| MOD_MON
    UTIL -->|"supports"| MOD_ORC
    UTIL -->|"supports"| MOD_REP
    UTIL -->|"supports"| MOD_SC
    UTIL -->|"supports"| MOD_TEN
    UTIL -->|"supports"| MOD_TRA

    %% External Services integrations
    CORE -->|"message broker"| RMQ
    UTIL -->|"queues"| RMQ
    DATA -->|"database operations"| PG
    DEP -->|"orchestrates"| API
    DEP -->|"orchestrates"| CORE
    DEP -->|"orchestrates"| DATA
    DEP -->|"orchestrates"| UTIL
    DEP -->|"orchestrates"| RMQ
    DEP -->|"orchestrates"| PG
    DEP -->|"orchestrates"| DIR
    API -->|"exposes docs"| DIR

    %% Direct connection from Data to External Content Service
    DATA -->|"syncs data"| DIR

    %% Click Events
    click CORE "https://github.com/citrineos/citrineos-core/tree/main/00_Base/src"
    click DATA "https://github.com/citrineos/citrineos-core/tree/main/01_Data/src"
    click UTIL "https://github.com/citrineos/citrineos-core/tree/main/02_Util/src"
    click MOD_CERT "https://github.com/citrineos/citrineos-core/tree/main/03_Modules/Certificates"
    click MOD_CONF "https://github.com/citrineos/citrineos-core/tree/main/03_Modules/Configuration"
    click MOD_EVD "https://github.com/citrineos/citrineos-core/tree/main/03_Modules/EVDriver"
    click MOD_MON "https://github.com/citrineos/citrineos-core/tree/main/03_Modules/Monitoring"
    click MOD_ORC "https://github.com/citrineos/citrineos-core/tree/main/03_Modules/OcppRouter"
    click MOD_REP "https://github.com/citrineos/citrineos-core/tree/main/03_Modules/Reporting"
    click MOD_SC "https://github.com/citrineos/citrineos-core/tree/main/03_Modules/SmartCharging"
    click MOD_TEN "https://github.com/citrineos/citrineos-core/tree/main/03_Modules/Tenant"
    click MOD_TRA "https://github.com/citrineos/citrineos-core/tree/main/03_Modules/Transactions"
    click API "https://github.com/citrineos/citrineos-core/blob/main/Server/src/index.ts"
    click DEP "https://github.com/citrineos/citrineos-core/tree/main/Server/"

    %% Styles
    classDef external fill:#ffcccc,stroke:#ff0000,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef database fill:#ffeeba,stroke:#856404,stroke-width:2px;
    classDef util fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef moduleDetail fill:#fdfd96,stroke:#999900,stroke-width:2px;
    classDef deployment fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef externalService fill:#e6ccff,stroke:#a64ca6,stroke-width:2px;
```
