How citrineos/citrineos-core works
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.).