# brainichq/tado-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/brainichq/tado-assistant
- Repository: https://github.com/brainichq/tado-assistant

## Overview

##### Main Components
- Service Scripts: The primary logic is encapsulated in the script (tado-assistant.sh), which runs in the background to monitor home state, perform open window detection, and interact with the Tado API.
- Installation and Update Manager: The install.sh script not only manages installation but also handles updates (including backup of local changes) and dependency setup.
- Environment Configuration: The file (typically /etc/tado-assistant.env) holds environment variables (e.g., authentication tokens, intervals, and logging configuration) which are critical for the runtime configuration.
- Docker Container: A Dockerfile is provided to package and run the application as a container, where users can perform device code flow authentication interactively.
- CI/CD and Deployment Files: The .github directory includes GitHub Actions workflows (e.g., docker-image.yml) and funding configuration, which shows the project’s integration with GitHub for continuous deployment and community support.

##### Relationships and Interactions
- The User initiates the installation process (via the install.sh script) which sets up dependencies, prompts for device code flow authentication (to obtain refresh tokens), and writes configuration into the environment file.
- Once installed, the service (tado-assistant.sh) is registered as a background service using system-level tools – systemd on Linux or launchctl on macOS.
- The Tado Assistant service interacts with the Tado API using credentials stored in the environment file. It continuously monitors the home’s state and responds to sensor input or authentication changes.
- For Docker deployments, the container images are built from the Dockerfile and run interactively if device code flow authentication is needed. The operational behavior inside the container remains the same as the service installed natively.
- GitHub workflows in .github/workflows support container building and other CI steps, ensuring code quality and automated deployment.

##### Architectural Pattern and Design Principles
- The project follows a simple script-driven, modular approach. While not a full-blown microservices architecture, it separates concerns between installation, configuration, and service execution.
- The design capitalizes on minimal dependencies (relying on standard Unix utilities such as curl and jq), making it lightweight and portable.
- The configuration via environment variables emphasizes flexibility and decoupled configuration, an important design principle for maintainability.

##### Integrating Relevant Technologies
- Shell scripting: The core logic is implemented in Bash scripts.
- Docker: Used for containerizing the application (Dockerfile).
- System-level service management: Uses systemd (Linux) or launchctl (macOS) for persistent background execution.
- CI/CD: GitHub workflows and associated YAML files to automate Docker image builds and possibly run tests.

- Installation Manager (install.sh)
- Main Service Script (tado-assistant.sh)
- Environment Configuration (/etc/tado-assistant.env)
- Docker Container (built from Dockerfile) as an alternative runtime environment.
- Service Management (systemd/launchctl)
- External Interaction (Tado API and third-party dependencies like curl and jq)
- From “User” to “Installation Manager”
- From “Installation Manager” to “Configuration File”
- From “Configuration File” to “Main Service Script”
- From “Main Service Script” to “Tado API” (indicating API calls and authentication)
- From “Main Service Script” to “Logging Module” (or log file: /var/log/tado-assistant.log)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User["User"]:::external

    %% Installation & Configuration
    subgraph "Installation & Configuration"
        Install["Installation Manager (install.sh)"]:::script
        Config["Environment Configuration (/etc/tado-assistant.env)"]:::config
    end

    %% Runtime Service
    subgraph "Runtime Service"
        Main["Main Service Script (tado-assistant.sh)"]:::script
        ServiceMgmt["Service Management (systemd/launchctl)"]:::infra
        Logging["Logging (/var/log/tado-assistant.log)"]:::log
        API["Tado API"]:::external
    end

    %% Deployment & CI/CD
    subgraph "Deployment"
        Docker["Docker Container (Dockerfile)"]:::container
        CICD1["CI/CD Workflow (docker-image.yml)"]:::cicd
        CICD2["CI/CD Funding Config (.github/FUNDING.yml)"]:::cicd
    end

    %% Connections
    User -->|"initiates"| Install
    Install -->|"sets_up"| Config
    Config -->|"configures"| Main
    Main -->|"registers_with"| ServiceMgmt
    Main -->|"logs_events"| Logging
    Main -->|"calls_API"| API
    
    CICD1 -->|"triggers_build"| Docker
    CICD2 -->|"provides_config"| Docker
    Docker -->|"runs_service"| Main
    Docker -->|"calls_API"| API

    %% Click Events
    click Install "https://github.com/brainichq/tado-assistant/blob/main/install.sh"
    click Main "https://github.com/brainichq/tado-assistant/blob/main/tado-assistant.sh"
    click Docker "https://github.com/brainichq/tado-assistant/tree/main/Dockerfile"
    click CICD1 "https://github.com/brainichq/tado-assistant/blob/main/.github/workflows/docker-image.yml"
    click CICD2 "https://github.com/brainichq/tado-assistant/blob/main/.github/FUNDING.yml"

    %% Styles
    classDef external fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef script fill:#C5E1A5,stroke:#333,stroke-width:2px;
    classDef config fill:#BBDEFB,stroke:#333,stroke-width:2px;
    classDef infra fill:#FFCDD2,stroke:#333,stroke-width:2px;
    classDef log fill:#E1BEE7,stroke:#333,stroke-width:2px;
    classDef container fill:#B3E5FC,stroke:#333,stroke-width:2px;
    classDef cicd fill:#D1C4E9,stroke:#333,stroke-width:2px;
```
