# kwindrem/setuphelper architecture

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

- Interactive diagram: https://gitdiagram.com/kwindrem/setuphelper
- Repository: https://github.com/kwindrem/setuphelper

## Overview

##### Project Type and Purpose
- Type: An embedded‐Linux package manager and installer for Venus OS on Victron GX devices.
- Purpose:
- Automate package install/update (from GitHub or USB)
- Reinstall packages after OS updates
- GUI integration for manual control, conflict resolution, backups/restores
- “Blind” install/uninstall at boot via removable media
- Uses runit services, DBus APIs, QML UI, shell helpers, Python modules

##### File Structure
- Top‐level components:
- services/PackageManager → runit directory for the PackageManager daemon
- velib_python/… → Python DBus monitor & helper library for interacting with Venus OS services
- FileSets/… → QML pages injected into the system GUI (patch & version-independent sets)
- HelperResources/… → Shared shell functions & hooks for package install/uninstall scripts
- blindInstall/… → Boot-time scripts & rcS.local hooks for “blind” install/uninstall
- Root scripts (PackageManager.py, setup, updatePackage, reinstallMods, makeVelib_python, etc.)
- GitHub workflows (.github/) and version metadata (version, changes, gitHubInfo)

##### Extract Insights from the README
- Core features (auto-reinstall, auto-update, blind install/uninstall)
- Conflict detection & resolution logic
- Use of HelperResources by third‐party packages
- OS hooks (rcS.local, swupdate-scripts) and DBus interactions

a. OS Foundation
- Venus OS (runit, swupdate-scripts, filesystem at /data, /opt)
- rcS.local
b. SetupHelper Core
1. BlindInstall Module
– blindInstall/rcS.local hooks
– pre-hook.sh, post-hook.sh
2. PackageManager Daemon
– services/PackageManager/run
– PackageManager.py
– Log directory (services/PackageManager/log)
3. GUI Extension
– FileSets/PatchSource QML pages (injected at runtime)
– VersionIndependent QML pages
4. HelperResources Library
– Shell scripts for install/uninstall operations
– Hook points for third-party packages
5. Python DBus API
– velib_python modules (dbusmonitor.py, vedbus.py, ve_utils.py, settingsdevice.py, oldestVersion.py)
c. External Interfaces
– GitHub archives (online update source)
– USB/SD media (offline update/install source)
– Venus OS swupdate for firmware updates
d. Persistent Storage
– /data/SetupHelper (archives, settings backups)
– Settings in com.victronenergy.settings

##### Relationships & Data Flows
- User clicks in the GUI → QML layer → sends DBus message
- Python DBus monitor (velib_python) receives requests → invokes PackageManager.py
- PackageManager daemon calls HelperResources shell functions → filesystem changes, service restarts
- OS update triggers swupdate-scripts → via runit signals → BlindInstall may reinstall packages
- Manual or scheduled checks fetch tarballs from GitHub or scan USB → hand off to PackageManager

##### Architectural Patterns & Principles
- Layered architecture: UI (QML) → DBus API (Python) → Service (PackageManager) → Shell Helpers → OS
- Modular Resource Injection: QML pages are patched in via FileSets
- Event‐Driven: DBus for inter‐component messaging, runit for service supervision
- Plugin-style Helpers: third-party packages source HelperResources for consistent install semantics

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Sources
    GitHubCloud{{"GitHub Archives"}}:::external
    USBCloud{{"USB/SD Media"}}:::external
    GitHubWF[".github/workflows/latest-tag.yml"]:::external

    %% GUI Extension Layer
    subgraph "GUI Extension" 
        direction LR
        PatchSourceQML["PatchSource QML\n(PageSettings.qml)"]:::ui
        VersionIndQML["VersionIndependent QML\n(PageSettingsPackageManager.qml)"]:::ui
    end

    %% Python DBus API Layer
    subgraph "Python DBus API (velib_python)" 
        direction TB
        DBusMonitor["dbusmonitor.py"]:::python
        VeDBus["vedbus.py"]:::python
        VeUtils["ve_utils.py"]:::python
        SettingsDevice["settingsdevice.py"]:::python
        OldestVer["oldestVersion"]:::python
        LatestPY["latest/…"]:::python
    end

    %% PackageManager Daemon
    subgraph "PackageManager Daemon" 
        direction TB
        PMRun["run"]:::runtime
        PMLogRun["log/run"]:::runtime
        PMPy["PackageManager.py"]:::runtime
    end

    %% HelperResources Library
    subgraph "HelperResources" 
        direction TB
        CommonRes["CommonResources"]:::helpers
        DbusSettingsRes["DbusSettingsResources"]:::helpers
        EssentialRes["EssentialResources"]:::helpers
        IncludeHelpers["IncludeHelpers"]:::helpers
        LogHandler["LogHandler"]:::helpers
        ServiceRes["ServiceResources"]:::helpers
        VersionRes["VersionResources"]:::helpers
        VersionFile["version"]:::helpers
    end

    %% BlindInstall Module
    subgraph "BlindInstall Module" 
        direction TB
        BlindHook["rcS.local hook"]:::os
        PreHook["pre-hook.sh"]:::os
        PostHook["post-hook.sh"]:::os
        BlindScript["blindInstall.sh"]:::os
    end

    %% Root Scripts
    subgraph "Root Scripts & Setup Helpers"
        direction TB
        Setup["setup"]:::runtime
        UpdatePkg["updatePackage"]:::runtime
        ReinstallMods["reinstallMods"]:::runtime
        MakeVelib["makeVelib_python"]:::runtime
        PmEnd["packageManagerEnd.sh"]:::runtime
        GenericSetup["genericSetupScript"]:::runtime
        ForSetup["forSetupScript"]:::runtime
        DefaultList["defaultPackageList"]:::runtime
        SettingsList["settingsList"]:::runtime
    end

    %% OS Foundation & Storage
    subgraph "OS Foundation & Storage"
        direction TB
        VenusOS["Venus OS\n(runit, swupdate-scripts)"]:::os
        RcSLocalRoot["rcS.local"]:::os
        DataStorage[/"data/SetupHelper"/]:::storage
        SettingsStore[/"com.victronenergy.settings"/]:::storage
    end

    %% Relationships
    PatchSourceQML -->|DBus call| DBusMonitor
    VersionIndQML -->|DBus call| DBusMonitor
    DBusMonitor -->|invoke| PMPy
    VeDBus -->|utilities| PMPy
    VeUtils -->|utils| PMPy
    SettingsDevice -->|device| PMPy
    OldestVer -->|version check| PMPy
    LatestPY -->|helpers| DBusMonitor

    PMPy -->|start service| PMRun
    PMRun -->|supervised| PMLogRun
    PMPy -->|shell invoke| CommonRes
    PMPy -->|shell invoke| DbusSettingsRes
    PMPy -->|shell invoke| EssentialRes
    PMPy -->|shell invoke| IncludeHelpers
    PMPy -->|shell invoke| LogHandler
    PMPy -->|shell invoke| ServiceRes
    PMPy -->|shell invoke| VersionRes
    PMPy -->|shell invoke| VersionFile

    BlindHook -->|boot triggers| PreHook
    PreHook -->|call| BlindScript
    BlindScript -->|call| PostHook
    VenusOS -->|boot hook| BlindHook

    GitHubCloud -->|tar.gz download| PMPy
    USBCloud -->|scan media| PMPy
    GitHubWF -->|workflow| GitHubCloud

    VenusOS -->|swupdate| BlindHook
    VenusOS -->|OS update| PMRun

    Setup -->|init| PMPy
    UpdatePkg -->|run| PMPy
    ReinstallMods -->|run| PMPy
    MakeVelib -->|build| LatestPY
    PmEnd -->|cleanup| PMPy
    GenericSetup -->|common| CommonRes
    ForSetup -->|common| CommonRes
    DefaultList -->|config| PMPy
    SettingsList -->|config| SettingsDevice

    DataStorage -->|stores| PMPy
    DataStorage -->|backups| ReinstallMods
    SettingsStore -->|persistent| SettingsDevice

    %% Click Events
    click BlindHook "https://github.com/kwindrem/setuphelper/blob/main/blindInstall/rcS.local"
    click PreHook "https://github.com/kwindrem/setuphelper/blob/main/blindInstall/pre-hook.sh"
    click PostHook "https://github.com/kwindrem/setuphelper/blob/main/blindInstall/post-hook.sh"
    click BlindScript "https://github.com/kwindrem/setuphelper/blob/main/blindInstall/blindInstall.sh"
    click PMRun "https://github.com/kwindrem/setuphelper/tree/main/services/PackageManager/run"
    click PMLogRun "https://github.com/kwindrem/setuphelper/tree/main/services/PackageManager/log/run"
    click PMPy "https://github.com/kwindrem/setuphelper/blob/main/PackageManager.py"
    click PatchSourceQML "https://github.com/kwindrem/setuphelper/blob/main/FileSets/PatchSource/PageSettings.qml"
    click VersionIndQML "https://github.com/kwindrem/setuphelper/blob/main/FileSets/VersionIndependent/PageSettingsPackageManager.qml"
    click CommonRes "https://github.com/kwindrem/setuphelper/tree/main/HelperResources/CommonResources"
    click DbusSettingsRes "https://github.com/kwindrem/setuphelper/tree/main/HelperResources/DbusSettingsResources"
    click EssentialRes "https://github.com/kwindrem/setuphelper/tree/main/HelperResources/EssentialResources"
    click IncludeHelpers "https://github.com/kwindrem/setuphelper/tree/main/HelperResources/IncludeHelpers"
    click LogHandler "https://github.com/kwindrem/setuphelper/tree/main/HelperResources/LogHandler"
    click ServiceRes "https://github.com/kwindrem/setuphelper/tree/main/HelperResources/ServiceResources"
    click VersionRes "https://github.com/kwindrem/setuphelper/tree/main/HelperResources/VersionResources"
    click VersionFile "https://github.com/kwindrem/setuphelper/tree/main/HelperResources/version"
    click DBusMonitor "https://github.com/kwindrem/setuphelper/blob/main/velib_python/dbusmonitor.py"
    click VeDBus "https://github.com/kwindrem/setuphelper/blob/main/velib_python/vedbus.py"
    click VeUtils "https://github.com/kwindrem/setuphelper/blob/main/velib_python/ve_utils.py"
    click SettingsDevice "https://github.com/kwindrem/setuphelper/blob/main/velib_python/settingsdevice.py"
    click OldestVer "https://github.com/kwindrem/setuphelper/tree/main/velib_python/oldestVersion"
    click LatestPY "https://github.com/kwindrem/setuphelper/tree/main/velib_python/velib_python/latest/"
    click RcSLocalRoot "https://github.com/kwindrem/setuphelper/blob/main/rcS.local"
    click GitHubWF "https://github.com/kwindrem/setuphelper/blob/main/.github/workflows/latest-tag.yml"
    click Setup "https://github.com/kwindrem/setuphelper/tree/main/setup"
    click UpdatePkg "https://github.com/kwindrem/setuphelper/tree/main/updatePackage"
    click ReinstallMods "https://github.com/kwindrem/setuphelper/tree/main/reinstallMods"
    click MakeVelib "https://github.com/kwindrem/setuphelper/tree/main/makeVelib_python"
    click PmEnd "https://github.com/kwindrem/setuphelper/blob/main/packageManagerEnd.sh"
    click GenericSetup "https://github.com/kwindrem/setuphelper/tree/main/genericSetupScript"
    click ForSetup "https://github.com/kwindrem/setuphelper/tree/main/forSetupScript"
    click DefaultList "https://github.com/kwindrem/setuphelper/tree/main/defaultPackageList"
    click SettingsList "https://github.com/kwindrem/setuphelper/tree/main/settingsList"

    %% Styles
    classDef runtime fill:#D0E6FF,stroke:#000,color:#000
    classDef ui fill:#D4F4DD,stroke:#000,color:#000
    classDef helpers fill:#FFF4C1,stroke:#000,color:#000
    classDef python fill:#FFE4B5,stroke:#000,color:#000
    classDef os fill:#E0E0E0,stroke:#000,color:#000
    classDef storage fill:#D2B48C,stroke:#000,color:#000
    classDef external fill:#ADD8E6,stroke:#000,color:#000
```
