# nielsu97/smart-home-dashboard architecture

> Architecture diagram of the GitHub repository nielsu97/smart-home-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nielsu97/smart-home-dashboard
- Repository: https://github.com/nielsu97/smart-home-dashboard

## Overview

##### Project type and purpose
- This is an embedded full-stack Qt/QML application targeted at a Raspberry Pi.
- Purpose: display and control Home Assistant entities (lights, climate, energy, music) via its REST API.

##### Top-level file‐structure analysis
- cpp/: C++ “backend” (main.cpp, backend.{cpp,h})
- qml/: QML “frontend” (Main.qml, components/, pane/)
- CMakeLists.txt / .pro: build configuration
- README.md: deployment & run instructions (systemd, eglfs)

##### Key architectural insights from README
- Qt6 (QNetworkAccessManager, JSON parsing, QML engine)
- Single binary SmartDashboard
- Deployed as a systemd service on Raspberry Pi, using eglfs for direct‐to‐framebuffer output
- Polls or subscribes to Home Assistant via its HTTP API (token + IP)

##### Main components
a. Hardware & OS layer
- Raspberry Pi (Linux + systemd)
- eglfs (Qt platform plugin)
b. Application layer
- C++ backend
– initializes QML engine
– manages QNetworkAccessManager for REST calls
– parses JSON entities (lights, climate, etc.)
– exposes data & methods to QML via QObject properties & slots
- QML frontend
– Main.qml (root)
– components/ (reusable controls)
– pane/ (feature pages: Home, Climate, Energy, Music)
c. External services
- Home Assistant API (HTTP over LAN)

##### Relationships & interactions
- On startup, systemd → starts SmartDashboard
- C++ main → sets up QML engine, loads Main.qml
- QML UI triggers C++ slots (e.g., toggle light)
- Backend issues HTTP GET/POST to Home Assistant → receives JSON → updates QML properties → UI refresh
- Data flows: Home Assistant → C++ → QML → user → C++ → Home Assistant

##### Architectural patterns & design principles
- MVC‐like separation: QML = View, C++ = Model+Controller
- Signal–slot mechanism for decoupling UI and logic
- Single‐process monolith deployed on device
- Systemd for lifecycle management

##### Essential elements to capture
- Clear, hierarchical layering (Hardware → OS → App → UI)
- All major code modules (cpp/, qml/)
- Data flow direction and trigger points (user actions, polling)
- Deployment & startup sequence (systemd, boot)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Hardware & OS Layer"
        RPi["Raspberry Pi\n(Linux + systemd)"]:::blue
        eglfs["eglfs\n(Qt platform plugin)"]:::blue
    end

    subgraph "Build & Deployment"
        CMake["CMakeLists.txt"]:::green
        Pro["SmartDashboard.pro"]:::green
        Qrc["qml.qrc"]:::green
    end

    subgraph "Documentation"
        Readme["README.md"]:::green
        Gitattributes[".gitattributes"]:::green
    end

    SmartExe["SmartDashboard Binary"]:::green

    subgraph "Application Layer"
        subgraph "C++ Backend" 
            MainCpp["main.cpp"]:::green
            BackendCpp["backend.cpp"]:::green
            BackendH["backend.h"]:::green
            QEngine["Qt Quick/QML Engine"]:::blue
            QNetwork["QNetworkAccessManager"]:::blue
        end

        subgraph "QML Frontend"
            MainQml["Main.qml"]:::green
            subgraph "Components"
                Button["Button.qml"]:::green
                CircProg["CircularProgressBar.qml"]:::green
                IconLabel["IconLabel.qml"]:::green
                ProgressBar["Progressbar.qml"]:::green
                Slider["Slider.qml"]:::green
                Switch["Switch.qml"]:::green
            end
            subgraph "Pane Modules"
                HomePane["HomePane.qml"]:::green
                ClimatePane["ClimatePane.qml"]:::green
                EnergyPane["EnergyPane.qml"]:::green
                MusicPane["MusicPane.qml"]:::green
                LeftPane["LeftPane.qml"]:::green
            end
            Assets["assets/fonts/fontawesome.otf"]:::green
        end
    end

    HomeAssistant["Home Assistant API\n(HTTP + Bearer Token)"]:::orange

    %% Connections
    RPi -->|"systemd start SmartDashboard"| SmartExe
    SmartExe -->|"loads"| QEngine
    QEngine -->|"renders via"| eglfs

    SmartExe -->|"executes"| MainCpp
    MainCpp -->|"initializes"| QEngine
    MainCpp -->|"creates"| QNetwork

    QNetwork -->|"HTTP GET/POST"| HomeAssistant
    HomeAssistant -->|"JSON response"| QNetwork

    QNetwork -->|"signals data"| BackendCpp
    BackendCpp & BackendH -->|"exposes QObject props/slots"| MainQml
    MainQml <-->|"signal/slot"| BackendCpp

    MainQml -->|"uses"| Button
    MainQml -->|"uses"| CircProg
    MainQml -->|"uses"| IconLabel
    MainQml -->|"uses"| ProgressBar
    MainQml -->|"uses"| Slider
    MainQml -->|"uses"| Switch

    MainQml -->|"loads panes"| HomePane
    MainQml -->|"loads panes"| ClimatePane
    MainQml -->|"loads panes"| EnergyPane
    MainQml -->|"loads panes"| MusicPane
    MainQml -->|"loads panes"| LeftPane

    MainQml -->|"loads assets"| Assets

    %% Click Events
    click MainCpp "https://github.com/nielsu97/smart-home-dashboard/blob/main/cpp/main.cpp"
    click BackendCpp "https://github.com/nielsu97/smart-home-dashboard/blob/main/cpp/backend.cpp"
    click BackendH "https://github.com/nielsu97/smart-home-dashboard/blob/main/cpp/backend.h"
    click MainQml "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml/Main.qml"
    click Button "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml/components/Button.qml"
    click CircProg "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml/components/CircularProgressBar.qml"
    click IconLabel "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml/components/IconLabel.qml"
    click ProgressBar "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml/components/Progressbar.qml"
    click Slider "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml/components/Slider.qml"
    click Switch "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml/components/Switch.qml"
    click HomePane "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml/pane/HomePane.qml"
    click ClimatePane "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml/pane/ClimatePane.qml"
    click EnergyPane "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml/pane/EnergyPane.qml"
    click MusicPane "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml/pane/MusicPane.qml"
    click LeftPane "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml/pane/LeftPane.qml"
    click Assets "https://github.com/nielsu97/smart-home-dashboard/blob/main/assets/fonts/fontawesome.otf"
    click CMake "https://github.com/nielsu97/smart-home-dashboard/blob/main/CMakeLists.txt"
    click Pro "https://github.com/nielsu97/smart-home-dashboard/blob/main/SmartDashboard.pro"
    click Qrc "https://github.com/nielsu97/smart-home-dashboard/blob/main/qml.qrc"
    click Readme "https://github.com/nielsu97/smart-home-dashboard/blob/main/README.md"
    click Gitattributes "https://github.com/nielsu97/smart-home-dashboard/blob/main/.gitattributes"

    classDef blue fill:#B3CDE3,stroke:#6497B1,color:#03396C;
    classDef green fill:#C7E9C0,stroke:#74C476,color:#006D2C;
    classDef orange fill:#FDD0A2,stroke:#FD8D3C,color:#8C2D04;
```
