# kwindrem/guimods architecture

> Architecture diagram of the GitHub repository kwindrem/guimods, 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/guimods
- Repository: https://github.com/kwindrem/guimods

## Overview

##### Project Type and Purpose
- This is neither a conventional full-stack web app nor a compiler. It’s an open-source GUI modification (“GuiMods”) package for the VenusOS embedded UI on Victron Energy devices (CCGX, panels, remote consoles).
- It supplies QML “overrides” and Python D-Bus services to enhance the stock UI (dark mode, new overviews, gauges, relay and generator controls, external transfer switch support).

##### File Structure Analysis
- **Top-level scripts**:
- ExtTransferSwitch.py – Python service entry point for external transfer-switch logic.
- services/ExtTransferSwitch/… – runit scripts to launch and supervise the above service on target device.
- **FileSets/**: Contains UI asset bundles organized by firmware version:
- PatchSource – QML and Python “.patch” files and originals, used by SetupHelper to generate patched QML for each target firmware.
- AlternateOriginals & VersionIndependent – supplemental and reusable QML/UI components.
- v3.xx folders – “complete” sets of QML overlays for specific VenusOS firmware versions.
- **Configuration files**:
- ReadMe – documents features, options, installation.
- setup, packageDependencies, version – metadata for PackageManager and SetupHelper.

##### Insights from README
- High-level architecture is described: QML overrides loaded in place of built-in GUI pages; Python services interact with VenusOS D-Bus to monitor and control external hardware (transfer switch, generator, relays).
- SetupHelper is a prerequisite installer that applies these patches and configures services.

##### Main Components & Interactions (
a. **Data Sources & Device Interfaces**
- Victron hardware: inverter/charger (Multi/Quattro), battery, PV charger/inverter, alternators, relays, tanks, temperature sensors.
- Data bus: VenusOS D-Bus (message bus exposing device metrics, status, control endpoints).
b. **Business Logic & Services**
- Python D-Bus modules in PatchSource (dbus_systemcalc.py, dbus_generator.py, dbus_*.py) – adapt or extend VenusOS system calculations and expose custom properties.
- ExtTransferSwitch service – listens on a programmed digital input and issues D-Bus commands to switch AC-input current limit and source type.
- runit scripts – supervise the Python service (services/ExtTransferSwitch/run & log/run).
- SetupHelper integration – scans PatchSource file trees, applies .patch files to original QML, and writes out version-specific overrides in FileSets/v3.xx.
c. **Presentation Layer (UI)**
- QML override files (main.qml, PageMain.qml, Overview*.qml, Detail*.qml, Tile*.qml) organized under FileSets for each firmware version.
- VersionIndependent QML – shared components (e.g., gauges, tiles, utility JS) loaded from a common path.
- The QML engine in VenusOS picks up these overrides (via search path ordering configured by PackageManager).
d. **Configuration & Control**
- User settings in Device List → Settings → Display & language → GuiMods menu control which overlays and enhancements to load at runtime.
- Settings are saved via VenusOS configuration services and read by SetupHelper and/or Python modules if needed.

##### Architectural Patterns & Design Principles
- **Patch/Override pattern**: Original UI pages remain intact; GuiMods supplies a parallel file tree of QML assets that override by matching filenames.
- **Version abstraction**: FileSets/v3.xx maintain complete sets per firmware version, while VersionIndependent holds shared components.
- **Separation of concerns**:
- UI declarative layer (QML) is strictly for presentation.
- Python D-Bus modules offer data transformation and control logic.
- runit services handle long-running tasks (transfer-switch monitoring).
- **Extensibility**: New UI variants can be added by dropping new QML files under FileSets, and new services via services/.

- A notation of versioning strategy (multiple v3.xx directories fed by patches).
- The runit service grouping (services/ExtTransferSwitch).

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "User & Hardware"
    User["User"]:::hardware
    Hardware["Victron Multi/Quattro,\nBattery,\nPV Charger,\nRelays,..."]:::hardware
  end

  subgraph "D-Bus & Services"
    DBus["VenusOS D-Bus"]:::services
    subgraph "Python Modules (PatchSource)"
      SYS["dbus_systemcalc.py"]:::services
      GEN["dbus_generator.py"]:::services
      DIGI["dbus_digitalinputs.py"]:::services
      SS["startstop.py"]:::services
    end
    ExtService["ExtTransferSwitch.py"]:::services
    subgraph "runit Supervisor"
      RunService["run"]:::supervisor
      RunLog["log/run"]:::supervisor
    end
    SetupHelper["SetupHelper & PackageManager\n(setup, metadata)"]:::services
  end

  subgraph "Patch & Build Pipeline"
    PS_QML["PatchSource QML & Python patches"]:::logic
    Orig_QML["Original QML/UI sources"]:::logic
    FileSets_v3["FileSets/v3.xx\n(complete QML overrides)"]:::ui
  end

  subgraph "UI Presentation Layer"
    VersionInd["VersionIndependent QML & JS"]:::ui
    AltOrig["AlternateOriginals QML"]:::ui
    UIOverrides["FileSets/v3.xx QML Overrides"]:::ui
  end

  Hardware -->|data updates| DBus
  DBus -->|published metrics| SYS
  DBus -->|published metrics| GEN
  DBus -->|published metrics| DIGI
  DBus -->|published metrics| SS
  SYS -->|extended properties| DBus
  GEN -->|extended properties| DBus
  DIGI -->|extended properties| DBus
  SS -->|control logic| DBus
  ExtService -->|listens input & issues commands| DBus
  RunService --> ExtService
  RunLog --> ExtService

  User -->|interactions| UIOverrides
  User -->|interactions| VersionInd
  UIOverrides -->|property binds| DBus
  VersionInd -->|shared components| UIOverrides

  PS_QML -->|patch application| SetupHelper
  Orig_QML -->|source inputs| SetupHelper
  SetupHelper -->|generates| FileSets_v3
  FileSets_v3 -->|runtime overrides| UIOverrides

  click ExtService "https://github.com/kwindrem/guimods/blob/main/ExtTransferSwitch.py"
  click RunService "https://github.com/kwindrem/guimods/tree/main/services/ExtTransferSwitch/run"
  click RunLog "https://github.com/kwindrem/guimods/tree/main/services/ExtTransferSwitch/log/run"
  click SYS "https://github.com/kwindrem/guimods/blob/main/FileSets/PatchSource/dbus_systemcalc.py-*.patch"
  click GEN "https://github.com/kwindrem/guimods/blob/main/FileSets/PatchSource/dbus_generator.py-*.patch"
  click DIGI "https://github.com/kwindrem/guimods/blob/main/FileSets/PatchSource/dbus_digitalinputs.py-*.patch"
  click SS "https://github.com/kwindrem/guimods/blob/main/FileSets/PatchSource/startstop.py-*.patch"
  click PS_QML "https://github.com/kwindrem/guimods/tree/main/FileSets/PatchSource/"
  click FileSets_v3 "https://github.com/kwindrem/guimods/tree/main/FileSets/v3.xx/"
  click VersionInd "https://github.com/kwindrem/guimods/tree/main/FileSets/VersionIndependent/"
  click AltOrig "https://github.com/kwindrem/guimods/tree/main/FileSets/AlternateOriginals/"
  click SetupHelper "https://github.com/kwindrem/guimods/tree/main/setup"

  classDef hardware fill:#ADD8E6,stroke:#000;
  classDef services fill:#90EE90,stroke:#000;
  classDef ui fill:#FFA500,stroke:#000;
  classDef supervisor fill:#D3D3D3,stroke:#000;
  classDef logic fill:#98FB98,stroke:#000;
```
