# tillsteinbach/carconnectivity architecture

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

- Interactive diagram: https://gitdiagram.com/tillsteinbach/carconnectivity
- Repository: https://github.com/tillsteinbach/carconnectivity

## Overview

##### Project Type and Purpose
- CarConnectivity is a Python API library intended to interface with various car services. Its purpose is to offer a unified way to connect to and extract data from different car brands via a plugin-based architecture.
- The project serves as a core library that third-party projects (like CLI interfaces, MQTT integrations, etc.) can build upon to interact with vehicles and their services.

##### Analyzing the File Structure
- The main source code is in the “src/carconnectivity” directory. This contains modules and classes handling vehicle attributes, battery, charging, drive, errors, utilities, and more.
- There are additional directories:
- “src/carconnectivity_connectors”: Contains base classes and UI components for connector implementations.
- “src/carconnectivity_plugins”: Contains base plugins and their UI support.
- “examples”: Provides usage examples demonstrating how to interact with various features of the library.
- “tests”: Contains test files ensuring the system's functionality.
- The top-level configuration files (like Makefile, pyproject.toml, and setup_requirements.txt) indicate that the project is well-structured and follows standard Python packaging and development practices.

##### Architectural Insights from the README
- The README highlights that the library uses a connector plugin architecture, allowing different car brands to be supported via specialized connectors.
- Additionally, a plugin system is mentioned for interfacing with external services (e.g., WebUI, MQTT, Homekit).
- The configuration snippet in the README shows that users specify their desired connectors via a JSON configuration file, which the library reads to initialize the appropriate components.

a. Main Components:
- Core Library (carconnectivity): This is the heart of the system containing modules for handling vehicle functionalities (e.g., battery, charging, climate control, drive, etc.).
- Connectors Layer: Under the “src/carconnectivity_connectors” directory, these represent adapters or interfaces for specific car brands (Volkswagen, Skoda, etc.).
- Plugins Layer: Found in “src/carconnectivity_plugins”, these offer connectivity to external services (MQTT, WebUI, etc.).
- Configuration Component: The JSON configuration (carconnectivity.json) which determines which connectors and plugins to load.
- External Consumer Applications: Projects (CLI tool, MQTT client, etc.) that make use of this library to provide higher-level functionality.
- Testing & Example Components: Illustrative examples (in “examples”) and tests to ensure proper integration and functionality.

b. Relationships and Interactions:
- The configuration file drives which connectors and plugins are active.
- The Core Library acts as a mediator by reading the configuration, instantiating connector objects from the connectors layer, and integrating any plugins as required.
- Connectors interact with the external car service APIs, gathering vehicle data and sending commands back.
- Plugins extend the core functionality by connecting to external systems (e.g., sending data to an MQTT broker).
- Data flows from the external car services through the connectors, then via the core library to any external consumers or plugins.

c. Important Architectural Patterns:
- Plugin Architecture: Emphasize how both connectors and plugins are implemented as interchangeable components with base classes providing the expected interfaces.
- Separation of Concerns: The core library handles business logic while connectors plug in distinct vehicle-specific integrations, and plugins handle interactions with external systems.
- Modularity and Extensibility: The design allows new connectors or plugins to be added easily by following the conventions established in the respective “base” directories.

d. Relevant Technologies and Libraries:
- Python is the primary language.
- Use of configuration formats such as JSON for setting up connectors.
- The structure implies usage of unit tests (likely using libraries such as pytest) and continuous integration workflows (via GitHub Actions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Component
    Config["Configuration (carconnectivity.json)"]:::config
    ConfigPt["pyproject.toml"]:::config
    ConfigReq["setup_requirements.txt"]:::config
    Config -->|"includes"| ConfigPt
    Config -->|"includes"| ConfigReq

    %% Core Library
    Core["Core Library"]:::core
    CarConn["carconnectivity.py"]:::core
    Battery["Battery Module"]:::core
    Charging["Charging Module"]:::core
    Drive["Drive Module"]:::core
    Core -->|"contains"| CarConn
    Core -->|"contains"| Battery
    Core -->|"contains"| Charging
    Core -->|"contains"| Drive

    %% Connectors Layer
    Connectors["Connectors Layer"]:::connector
    ConnectorBase["Connector Base"]:::connector
    ConnectorUI["Connector UI"]:::connector
    Connectors -->|"includes"| ConnectorBase
    Connectors -->|"includes"| ConnectorUI

    %% Plugins Layer
    Plugins["Plugins Layer"]:::plugin
    PluginBase["Plugin Base"]:::plugin
    PluginUI["Plugin UI"]:::plugin
    Plugins -->|"includes"| PluginBase
    Plugins -->|"includes"| PluginUI

    %% External Consumers
    Consumers["External Consumers (CLI, MQTT, etc.)"]:::consumer

    %% Examples and Testing
    Examples["Examples & Testing"]:::example
    ExampleAll["Example: all_cars.py"]:::example
    ExampleCharge["Example: start_stop_charging.py"]:::example
    Tests["Tests (__init__.py)"]:::test
    Examples -->|"contains"| ExampleAll
    Examples -->|"contains"| ExampleCharge
    Examples -->|"contains"| Tests

    %% Relationships between major components
    Config -->|"drives"| Core
    Core -->|"loads"| Connectors
    Core -->|"integrates"| Plugins
    Core -->|"provides data"| Consumers
    Core -->|"validated by"| Examples

    %% Click Events for Core Library Components
    click CarConn "https://github.com/tillsteinbach/carconnectivity/blob/main/src/carconnectivity/carconnectivity.py"
    click Battery "https://github.com/tillsteinbach/carconnectivity/blob/main/src/carconnectivity/battery.py"
    click Charging "https://github.com/tillsteinbach/carconnectivity/blob/main/src/carconnectivity/charging.py"
    
    %% Click Events for Connectors Layer Components
    click ConnectorBase "https://github.com/tillsteinbach/carconnectivity/blob/main/src/carconnectivity_connectors/base/connector.py"
    click ConnectorUI "https://github.com/tillsteinbach/carconnectivity/blob/main/src/carconnectivity_connectors/base/ui/connector_ui.py"
    
    %% Click Events for Plugins Layer Components
    click PluginBase "https://github.com/tillsteinbach/carconnectivity/blob/main/src/carconnectivity_plugins/base/plugin.py"
    click PluginUI "https://github.com/tillsteinbach/carconnectivity/blob/main/src/carconnectivity_plugins/base/ui/plugin_ui.py"
    
    %% Click Events for Configuration Files
    click ConfigPt "https://github.com/tillsteinbach/carconnectivity/blob/main/pyproject.toml"
    click ConfigReq "https://github.com/tillsteinbach/carconnectivity/blob/main/setup_requirements.txt"
    
    %% Click Events for Examples & Testing Components
    click ExampleAll "https://github.com/tillsteinbach/carconnectivity/blob/main/examples/all_cars.py"
    click ExampleCharge "https://github.com/tillsteinbach/carconnectivity/blob/main/examples/start_stop_charging.py"
    click Tests "https://github.com/tillsteinbach/carconnectivity/blob/main/tests/__init__.py"

    %% Styling
    classDef core fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef connector fill:#ccf2ff,stroke:#006699,stroke-width:2px;
    classDef plugin fill:#d0f0c0,stroke:#008000,stroke-width:2px;
    classDef config fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef consumer fill:#ffd9cc,stroke:#cc6600,stroke-width:2px;
    classDef example fill:#e6e6fa,stroke:#6666ff,stroke-width:2px;
    classDef test fill:#f2f2f2,stroke:#666666,stroke-width:2px;
```
