# jtm2kfpv-git/gigactl-g5-mf5 architecture

> Architecture diagram of the GitHub repository jtm2kfpv-git/gigactl-g5-mf5, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jtm2kfpv-git/gigactl-g5-mf5
- Repository: https://github.com/jtm2kfpv-git/gigactl-g5-mf5

## Overview

gigactl provides daemon-backed fan and keyboard controls, a desktop interface, and a separate Bazzite G5 MF5 manual controller. The main workflow runs from the desktop or CLI through the system-bus daemon to EC access; the daemon also samples telemetry and evaluates automatic fan curves. The Bazzite UI is a separate implementation. Some subsystem paths and links are documented but their source was not sampled, so those relationships are omitted rather than inferred.

Main entry points: [`daemon/gigactld/service.py`](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/service.py) (D-Bus service), [`gui/gigactl_gui/client.py`](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/client.py) (D-Bus client), [`gui/gigactl_gui/app.py`](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/app.py) (GigaControl app), [`gui/gigactl_gui/window.py`](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/window.py) (Overview window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_daemon["Daemon control"]
  node_daemon_service["D-Bus service<br/>[service.py]"]
  node_authorization["Polkit authorization<br/>[authz.py]"]
  node_state["Saved state<br/>[state.py]"]
end

subgraph group_hardware["EC hardware"]
  node_fan_control["Fan control<br/>[fans.py]"]
  node_keyboard_control["Keyboard control<br/>[keyboard.py]"]
  node_ec_access["EC access layer<br/>[ec.py]"]
  node_mailbox["EC mailbox<br/>[mailbox.py]"]
end

subgraph group_desktop["Desktop app"]
  node_app["GigaControl app<br/>[app.py]"]
  node_overview["Overview window<br/>[window.py]"]
  node_curve_editor["Curve editor page<br/>[curve_page.py]"]
  node_gui_client["D-Bus client<br/>[client.py]"]
  node_tray["Tray controls<br/>[tray.py]"]
  node_tray_menu["Tray menu<br/>[tray_menu.py]"]
  node_preview["Keyboard preview<br/>[preview.py]"]
end

subgraph group_bazzite["Bazzite controller"]
  node_bazzite_ui["Manual fan dashboard<br/>[gfan_ui.py]"]
  node_bazzite_curve["Cooling curve logic<br/>[gfan_curve.py]"]
  node_load_reader["CPU and GPU load<br/>[gfan_load.py]"]
  node_bazzite_cli["Manual fan controller<br/>[gfan.py]"]
  node_acpi_driver["ACPI EC interface<br/>[acpi_ec.c]"]
end

subgraph group_shared["Curve and telemetry"]
  node_curve_engine["Fan curve engine<br/>[curve.py]"]
  node_telemetry["Telemetry sampling<br/>[telemetry.py]"]
end

node_user(("Laptop user"))
node_cli["Fan and keyboard CLI"]
node_laptop_ec["Laptop embedded controller"]

node_user -->|"opens"| node_app
node_user -->|"runs"| node_cli
node_app -->|"shows"| node_overview
node_app -->|"starts"| node_tray
node_app -->|"connects"| node_gui_client
node_overview -->|"opens"| node_curve_editor
node_overview -->|"requests state"| node_gui_client
node_overview -.->|"updates"| node_preview
node_tray -->|"uses"| node_tray_menu
node_tray_menu -->|"reads profiles"| node_gui_client
node_curve_editor -->|"sends controls"| node_gui_client
node_gui_client -->|"calls over D-Bus"| node_daemon_service
node_cli -->|"controls over D-Bus"| node_daemon_service
node_daemon_service -->|"authorizes requests"| node_authorization
node_daemon_service -->|"dispatches fan control"| node_fan_control
node_daemon_service -->|"dispatches keyboard control"| node_keyboard_control
node_daemon_service -->|"reads and writes"| node_ec_access
node_daemon_service -->|"evaluates curves"| node_curve_engine
node_daemon_service -->|"publishes telemetry"| node_telemetry
node_daemon_service -->|"loads and saves"| node_state
node_fan_control -->|"issues commands"| node_mailbox
node_keyboard_control -->|"issues commands"| node_mailbox
node_ec_access -->|"accesses"| node_laptop_ec
node_mailbox -->|"writes registers"| node_ec_access
node_user -->|"uses"| node_bazzite_ui
node_user -->|"runs"| node_bazzite_cli
node_bazzite_ui -->|"uses"| node_bazzite_curve
node_bazzite_ui -->|"samples load"| node_load_reader

click node_app "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/app.py"
click node_overview "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/window.py"
click node_curve_editor "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/curve_page.py"
click node_gui_client "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/client.py"
click node_tray "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/tray.py"
click node_tray_menu "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/tray_menu.py"
click node_preview "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/preview.py"
click node_daemon_service "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/service.py"
click node_authorization "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/authz.py"
click node_state "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/state.py"
click node_fan_control "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/fans.py"
click node_keyboard_control "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/keyboard.py"
click node_ec_access "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/ec.py"
click node_mailbox "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/mailbox.py"
click node_curve_engine "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/curve.py"
click node_telemetry "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/telemetry.py"
click node_bazzite_ui "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/bazzite-g5-mf5/gfan_ui.py"
click node_bazzite_curve "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/bazzite-g5-mf5/gfan_curve.py"
click node_load_reader "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/bazzite-g5-mf5/gfan_load.py"
click node_bazzite_cli "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/bazzite-g5-mf5/gfan.py"
click node_acpi_driver "https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/bazzite-g5-mf5/acpi_ec/src/acpi_ec.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_daemon_service,node_authorization,node_state,node_user toneBlue
class node_fan_control,node_keyboard_control,node_ec_access,node_mailbox toneAmber
class node_app,node_overview,node_curve_editor,node_gui_client,node_tray,node_tray_menu,node_preview toneMint
class node_bazzite_ui,node_bazzite_curve,node_load_reader,node_bazzite_cli,node_acpi_driver toneRose
class node_curve_engine,node_telemetry,node_cli,node_laptop_ec toneIndigo
```

## Components

### Daemon control

- [D-Bus service](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/service.py): `daemon/gigactld/service.py`
- [Polkit authorization](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/authz.py): `daemon/gigactld/authz.py`
- [Saved state](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/state.py): `daemon/gigactld/state.py`

### EC hardware

- [Fan control](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/fans.py): `daemon/gigactld/fans.py`
- [Keyboard control](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/keyboard.py): `daemon/gigactld/keyboard.py`
- [EC access layer](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/ec.py): `daemon/gigactld/ec.py`
- [EC mailbox](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/mailbox.py): `daemon/gigactld/mailbox.py`

### Desktop app

- [GigaControl app](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/app.py): `gui/gigactl_gui/app.py`
- [Overview window](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/window.py): `gui/gigactl_gui/window.py`
- [Curve editor page](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/curve_page.py): `gui/gigactl_gui/curve_page.py`
- [D-Bus client](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/client.py): `gui/gigactl_gui/client.py`
- [Tray controls](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/tray.py): `gui/gigactl_gui/tray.py`
- [Tray menu](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/tray_menu.py): `gui/gigactl_gui/tray_menu.py`
- [Keyboard preview](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/gui/gigactl_gui/preview.py): `gui/gigactl_gui/preview.py`

### Bazzite controller

- [Manual fan dashboard](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/bazzite-g5-mf5/gfan_ui.py): `bazzite-g5-mf5/gfan_ui.py`
- [Cooling curve logic](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/bazzite-g5-mf5/gfan_curve.py): `bazzite-g5-mf5/gfan_curve.py`
- [CPU and GPU load](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/bazzite-g5-mf5/gfan_load.py): `bazzite-g5-mf5/gfan_load.py`
- [Manual fan controller](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/bazzite-g5-mf5/gfan.py): `bazzite-g5-mf5/gfan.py`
- [ACPI EC interface](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/bazzite-g5-mf5/acpi_ec/src/acpi_ec.c): `bazzite-g5-mf5/acpi_ec/src/acpi_ec.c`

### Curve and telemetry

- [Fan curve engine](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/curve.py): `daemon/gigactld/curve.py`
- [Telemetry sampling](https://github.com/jtm2kfpv-git/gigactl-g5-mf5/blob/master/daemon/gigactld/telemetry.py): `daemon/gigactld/telemetry.py`

### Other components

- **Laptop user**
- **Fan and keyboard CLI**
- **Laptop embedded controller**

## Connections

- Laptop user → GigaControl app: opens
- Laptop user → Fan and keyboard CLI: runs
- GigaControl app → Overview window: shows (evidence: `gui/gigactl_gui/app.py`)
- GigaControl app → Tray controls: starts (evidence: `gui/gigactl_gui/app.py`)
- GigaControl app → D-Bus client: connects (evidence: `gui/gigactl_gui/app.py`)
- Overview window → Curve editor page: opens (evidence: `gui/gigactl_gui/window.py`)
- Overview window → D-Bus client: requests state (evidence: `gui/gigactl_gui/window.py`)
- Overview window → Keyboard preview: updates (evidence: `gui/gigactl_gui/window.py`)
- Tray controls → Tray menu: uses (evidence: `gui/gigactl_gui/tray.py`)
- Tray menu → D-Bus client: reads profiles (evidence: `gui/gigactl_gui/tray_menu.py`)
- Curve editor page → D-Bus client: sends controls (evidence: `gui/gigactl_gui/curve_page.py`)
- D-Bus client → D-Bus service: calls over D-Bus
- Fan and keyboard CLI → D-Bus service: controls over D-Bus
- D-Bus service → Polkit authorization: authorizes requests (evidence: `daemon/gigactld/service.py`)
- D-Bus service → Fan control: dispatches fan control (evidence: `daemon/gigactld/service.py`)
- D-Bus service → Keyboard control: dispatches keyboard control (evidence: `daemon/gigactld/service.py`)
- D-Bus service → EC access layer: reads and writes (evidence: `daemon/gigactld/service.py`)
- D-Bus service → Fan curve engine: evaluates curves (evidence: `daemon/gigactld/service.py`)
- D-Bus service → Telemetry sampling: publishes telemetry (evidence: `daemon/gigactld/service.py`)
- D-Bus service → Saved state: loads and saves (evidence: `daemon/gigactld/service.py`)
- Fan control → EC mailbox: issues commands (evidence: `daemon/gigactld/fans.py`)
- Keyboard control → EC mailbox: issues commands (evidence: `daemon/gigactld/keyboard.py`)
- EC access layer → Laptop embedded controller: accesses
- EC mailbox → EC access layer: writes registers (evidence: `daemon/gigactld/mailbox.py`)
- Laptop user → Manual fan dashboard: uses
- Laptop user → Manual fan controller: runs
- Manual fan dashboard → Cooling curve logic: uses (evidence: `bazzite-g5-mf5/gfan_ui.py`)
- Manual fan dashboard → CPU and GPU load: samples load (evidence: `bazzite-g5-mf5/gfan_ui.py`)
