# teslamate-org/teslamate architecture

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

- Interactive diagram: https://gitdiagram.com/teslamate-org/teslamate
- Repository: https://github.com/teslamate-org/teslamate

## Overview

##### Main Components
- Core Application (TeslaMate Engine): Represent the heart of the system where the business logic lives. This includes modules for:
- Tesla API integrations (see lib/tesla_api and its subdirectories for authentication, middleware, vehicle data processing, streaming, etc.).
- Data import features (CSV importers under lib/teslamate/import).
- Log and state management components (inside lib/teslamate/log and lib/teslamate/vehicles).
- Application supervision and OTP lifecycle (modules like lib/teslamate/application.ex).

- Web Interface: Built on the Phoenix framework:
- Web controllers, live views, templates, and views (in lib/teslamate_web). This component handles the HTTP endpoint, real-time data display (live components), and admin interfaces.

- Database (Postgres):
- The Ecto repository (lib/teslamate/repo.ex) and related migration scripts (located in priv/repo/migrations) ensure that data is stored and maintained.

- MQTT Integration:
- Modules for publishing and subscribing to vehicle data (see lib/teslamate/mqtt and its submodules).

- External Dashboard/Visualization:
- Grafana integration, including container configuration (instances in the grafana folder) and dashboards (JSON files under grafana/dashboards) that fetch data from the database or MQTT.

- Assets & Website Documentation:
- The assets directory contains CSS, JavaScript, and build scripts for the web client.
- There is also a "website" folder that holds documentation, guides, and other static content (used to showcase screenshots and integration instructions).

##### Out Relationships and Interactions
- Data Flow from Tesla Vehicles to Persistence:
- The Tesla API module connects to Tesla endpoints or subscribed stream data.
- Incoming vehicle data is managed by the TeslaMate core modules and stored into the Postgres database via the Ecto repo.

- User Interaction via the Web Interface:
- Users connect to the dashboard served by the Phoenix application.
- Web controllers query the database for drive reports, battery health, charging stats, etc., and render them via live views and templates.

- External Integrations:
- MQTT modules publish vehicle states to an MQTT broker, allowing integration with Home Assistant or Node-RED.
- Grafana dashboards pull data either directly from the database or via data sources set up through the dashboards’ configuration, providing visual reports.

##### Architectural Patterns & Design Principles
- Separation of Concerns:
- The clear separation between Tesla API integration, business logic, web serving, and data persistence (database layer).
- Modular Structure:
- Distinct subcomponents (tesla_api, teslamate, teslamate_web) each responsible for specific areas.
- Reliability & Scalability:
- The use of OTP’s supervision trees ensures that components (e.g., data streaming, MQTT handling) are resilient.
- Extensibility:
- MQTT and CSV importers are designed for easy integration with other systems.

##### Relevant Technologies & Tools
- Elixir & Phoenix – Main programming language and web framework.
- Postgres – Relational database used with Ecto.
- Grafana – Visualization platform.
- MQTT Broker – For real-time messaging with external systems.
- Docker & CI/CD (GitHub workflows, Dockerfiles) – For deployment and continuous integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Application (TeslaMate Engine)
    subgraph "Core Application (TeslaMate Engine)"
        TAPI["Tesla API Integrations"]:::engine
        DI["Data Import Features"]:::engine
        LSM["Log & State Management"]:::engine
        APS["Application Supervision & OTP"]:::engine
        ENG["TeslaMate Engine"]:::engine
    end

    TAPI -->|"ingest"| ENG
    DI   -->|"ingest"| ENG
    LSM  -->|"update"| ENG
    APS  -->|"manage"| ENG

    %% Web Layer
    subgraph "Web Layer"
        WI["Web Interface (Phoenix)"]:::web
        AS["Assets (CSS/JS)"]:::web
        WD["Website Documentation"]:::web
    end

    %% Supporting Components
    DB["Postgres Database"]:::db
    MQTT["MQTT Integration"]:::mqtt
    GRAF["Grafana Dashboard/Visualization"]:::grafana

    %% Relationships between layers and integrations
    ENG -->|"DBWrite"| DB
    ENG -->|"MQTTPublish"| MQTT
    DB -->|"DBQuery"| WI
    DB -->|"DataPull"| GRAF

    %% Click Events for Component Mapping
    click TAPI "https://github.com/teslamate-org/teslamate/tree/master/lib/tesla_api"
    click DI "https://github.com/teslamate-org/teslamate/tree/master/lib/teslamate/import"
    click LSM "https://github.com/teslamate-org/teslamate/tree/master/lib/teslamate/log"
    click APS "https://github.com/teslamate-org/teslamate/blob/master/lib/teslamate/application.ex"
    click WI "https://github.com/teslamate-org/teslamate/tree/master/lib/teslamate_web"
    click DB "https://github.com/teslamate-org/teslamate/blob/master/lib/teslamate/repo.ex"
    click DB "https://github.com/teslamate-org/teslamate/tree/master/priv/repo/migrations"
    click MQTT "https://github.com/teslamate-org/teslamate/tree/master/lib/teslamate/mqtt"
    click GRAF "https://github.com/teslamate-org/teslamate/tree/master/grafana/dashboards"
    click AS "https://github.com/teslamate-org/teslamate/tree/master/assets"
    click WD "https://github.com/teslamate-org/teslamate/tree/master/website"

    %% Styles
    classDef engine fill:#FFCCCC,stroke:#CC0000,stroke-width:2px;
    classDef web fill:#CCFFCC,stroke:#009900,stroke-width:2px;
    classDef db fill:#CCCCFF,stroke:#0000CC,stroke-width:2px;
    classDef mqtt fill:#FFFFCC,stroke:#999900,stroke-width:2px;
    classDef grafana fill:#CCE5FF,stroke:#0055AA,stroke-width:2px;
```
