# jkuhl-dev/fedora-desktop architecture

> Architecture diagram of the GitHub repository jkuhl-dev/fedora-desktop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jkuhl-dev/fedora-desktop
- Repository: https://github.com/jkuhl-dev/fedora-desktop

## Overview

Fedora Desktop Configurator lets users select desktop and software changes, save or load profiles, and apply them through either the GTK interface or a profile-driven CLI. The main runtime path is application entry → option selection/profile loading → setup orchestration → Fedora and desktop-system changes. The repository also contains dedicated application-setup, VPN, and system-configuration scripts. Relationships below follow the shown imports/calls and README workflow; some script-to-option wiring and unsampled setup branches are not visible in the excerpts.

Main entry points: [`src/workflows/setup.py`](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/workflows/setup.py) (Setup orchestrator), [`src/gui/AdwApp.py`](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/gui/AdwApp.py) (GTK / CLI app), [`src/utils/sudo_utils.py`](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/sudo_utils.py) (Privilege elevation), [`src/data/OptionStore.py`](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/OptionStore.py) (Option and profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_main["Program entry<br/>[main.py]"]
  node_app["GTK / CLI app<br/>[AdwApp.py]"]
  node_window["Option window<br/>[MainWindow.py]"]
  node_info["App metadata<br/>[Info.py]"]
end

subgraph group_options["Options and profiles"]
  node_store["Option and profiles<br/>[OptionStore.py]"]
  node_option["Option actions<br/>[Option.py]"]
  node_category["Option categories<br/>[Category.py]"]
  node_operation["Action types<br/>[OperationType.py]"]
  node_paths["Resource paths<br/>[Paths.py]"]
end

subgraph group_execution["Setup execution"]
  node_setup["Setup orchestrator<br/>[setup.py]"]
end

subgraph group_system["System utilities"]
  node_platform["Desktop settings<br/>[platform_utils.py]"]
  node_dnf["RPM packages<br/>[dnf_utils.py]"]
  node_flatpak["Flatpak packages<br/>[flatpak_utils.py]"]
  node_extensions["GNOME extensions"]
  node_sudo["Privilege elevation<br/>[sudo_utils.py]"]
  node_prompts["User prompts<br/>[zenity_utils.py]"]
  node_caffeine["Sleep prevention<br/>[caffeine_utils.py]"]
  node_files["File operations<br/>[file_utils.py]"]
  node_vpn["VPN helpers<br/>[vpn_utils.py]"]
  node_print["Console output<br/>[print_utils.py]"]
end

subgraph group_scripts["Configuration scripts"]
  node_scripts["Setup scripts"]
  node_appscripts["Application setup"]
  node_vpnscripts["VPN setup"]
end

node_user(("Desktop user"))

node_user -->|"launches"| node_main
node_main -->|"starts"| node_app
node_app -->|"opens"| node_window
node_app -->|"loads profile"| node_store
node_app -->|"runs CLI setup"| node_setup
node_window -->|"manages selections"| node_store
node_window -->|"starts setup"| node_setup
node_store -->|"loads options"| node_option
node_option -->|"uses"| node_category
node_option -->|"stores actions"| node_operation
node_setup -->|"reads active options"| node_store
node_setup -->|"dispatches actions"| node_operation
node_setup -->|"installs packages"| node_dnf
node_setup -->|"installs Flatpaks"| node_flatpak
node_setup -->|"applies settings"| node_platform
node_setup -->|"manages extensions"| node_extensions
node_setup -->|"loads scripts"| node_scripts
node_scripts -.->|"includes"| node_appscripts
node_scripts -.->|"includes"| node_vpnscripts
node_setup -->|"prevents sleep"| node_caffeine
node_setup -->|"requests authentication"| node_sudo
node_sudo -->|"requests password"| node_prompts
node_sudo -->|"handles cancellation"| node_caffeine
node_dnf -->|"runs privileged commands"| node_sudo
node_flatpak -->|"runs privileged commands"| node_sudo
node_files -->|"copies system files"| node_sudo
node_setup -->|"prints progress"| node_print
node_app -->|"reads distro"| node_platform
node_app -->|"selects CLI prompts"| node_prompts
node_store -->|"uses options directory"| node_paths
node_main -->|"uses app metadata"| node_info

click node_main "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/main.py"
click node_app "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/gui/AdwApp.py"
click node_window "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/gui/MainWindow.py"
click node_store "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/OptionStore.py"
click node_option "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/Option.py"
click node_category "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/Category.py"
click node_operation "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/OperationType.py"
click node_setup "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/workflows/setup.py"
click node_scripts "https://github.com/jkuhl-dev/fedora-desktop/tree/main/src/scripts"
click node_appscripts "https://github.com/jkuhl-dev/fedora-desktop/tree/main/src/scripts/application"
click node_vpnscripts "https://github.com/jkuhl-dev/fedora-desktop/tree/main/src/scripts/vpn"
click node_platform "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/platform_utils.py"
click node_dnf "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/dnf_utils.py"
click node_flatpak "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/flatpak_utils.py"
click node_extensions "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/gnome_extension_utils.py"
click node_sudo "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/sudo_utils.py"
click node_prompts "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/zenity_utils.py"
click node_caffeine "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/caffeine_utils.py"
click node_files "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/file_utils.py"
click node_vpn "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/vpn_utils.py"
click node_paths "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/Paths.py"
click node_info "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/Info.py"
click node_print "https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/print_utils.py"

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_main,node_app,node_window,node_info,node_user toneBlue
class node_store,node_option,node_category,node_operation,node_paths toneAmber
class node_setup toneMint
class node_platform,node_dnf,node_flatpak,node_extensions,node_sudo,node_prompts,node_caffeine,node_files,node_vpn,node_print toneRose
class node_scripts,node_appscripts,node_vpnscripts toneIndigo
```

## Components

### Application entry

- [Program entry](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/main.py): `src/main.py`
- [GTK / CLI app](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/gui/AdwApp.py): `src/gui/AdwApp.py`
- [Option window](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/gui/MainWindow.py): `src/gui/MainWindow.py`
- [App metadata](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/Info.py): `src/data/Info.py`

### Options and profiles

- [Option and profiles](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/OptionStore.py): `src/data/OptionStore.py`
- [Option actions](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/Option.py): `src/data/Option.py`
- [Option categories](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/Category.py): `src/data/Category.py`
- [Action types](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/OperationType.py): `src/data/OperationType.py`
- [Resource paths](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/data/Paths.py): `src/data/Paths.py`

### Setup execution

- [Setup orchestrator](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/workflows/setup.py): `src/workflows/setup.py`

### System utilities

- [Desktop settings](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/platform_utils.py): `src/utils/platform_utils.py`
- [RPM packages](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/dnf_utils.py): `src/utils/dnf_utils.py`
- [Flatpak packages](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/flatpak_utils.py): `src/utils/flatpak_utils.py`
- [GNOME extensions](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/gnome_extension_utils.py): `src/utils/gnome_extension_utils.py`
- [Privilege elevation](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/sudo_utils.py): `src/utils/sudo_utils.py`
- [User prompts](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/zenity_utils.py): `src/utils/zenity_utils.py`
- [Sleep prevention](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/caffeine_utils.py): `src/utils/caffeine_utils.py`
- [File operations](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/file_utils.py): `src/utils/file_utils.py`
- [VPN helpers](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/vpn_utils.py): `src/utils/vpn_utils.py`
- [Console output](https://github.com/jkuhl-dev/fedora-desktop/blob/main/src/utils/print_utils.py): `src/utils/print_utils.py`

### Configuration scripts

- [Setup scripts](https://github.com/jkuhl-dev/fedora-desktop/tree/main/src/scripts): `src/scripts`
- [Application setup](https://github.com/jkuhl-dev/fedora-desktop/tree/main/src/scripts/application): `src/scripts/application`
- [VPN setup](https://github.com/jkuhl-dev/fedora-desktop/tree/main/src/scripts/vpn): `src/scripts/vpn`

### Other components

- **Desktop user**

## Connections

- Desktop user → Program entry: launches
- Program entry → GTK / CLI app: starts (evidence: `src/main.py`)
- GTK / CLI app → Option window: opens (evidence: `src/gui/AdwApp.py`)
- GTK / CLI app → Option and profiles: loads profile (evidence: `src/gui/AdwApp.py`)
- GTK / CLI app → Setup orchestrator: runs CLI setup (evidence: `src/gui/AdwApp.py`)
- Option window → Option and profiles: manages selections (evidence: `src/gui/MainWindow.py`)
- Option window → Setup orchestrator: starts setup (evidence: `src/gui/MainWindow.py`)
- Option and profiles → Option actions: loads options (evidence: `src/data/OptionStore.py`)
- Option actions → Option categories: uses (evidence: `src/data/Option.py`)
- Option actions → Action types: stores actions
- Setup orchestrator → Option and profiles: reads active options (evidence: `src/workflows/setup.py`)
- Setup orchestrator → Action types: dispatches actions (evidence: `src/workflows/setup.py`)
- Setup orchestrator → RPM packages: installs packages (evidence: `src/workflows/setup.py`)
- Setup orchestrator → Flatpak packages: installs Flatpaks (evidence: `src/workflows/setup.py`)
- Setup orchestrator → Desktop settings: applies settings (evidence: `src/workflows/setup.py`)
- Setup orchestrator → GNOME extensions: manages extensions (evidence: `src/workflows/setup.py`)
- Setup orchestrator → Setup scripts: loads scripts (evidence: `src/workflows/setup.py`)
- Setup scripts → Application setup: includes
- Setup scripts → VPN setup: includes
- Setup orchestrator → Sleep prevention: prevents sleep (evidence: `src/workflows/setup.py`)
- Setup orchestrator → Privilege elevation: requests authentication (evidence: `src/workflows/setup.py`)
- Privilege elevation → User prompts: requests password (evidence: `src/utils/sudo_utils.py`)
- Privilege elevation → Sleep prevention: handles cancellation (evidence: `src/utils/sudo_utils.py`)
- RPM packages → Privilege elevation: runs privileged commands (evidence: `src/utils/dnf_utils.py`)
- Flatpak packages → Privilege elevation: runs privileged commands (evidence: `src/utils/flatpak_utils.py`)
- File operations → Privilege elevation: copies system files (evidence: `src/utils/file_utils.py`)
- Setup orchestrator → Console output: prints progress (evidence: `src/workflows/setup.py`)
- GTK / CLI app → Desktop settings: reads distro (evidence: `src/gui/AdwApp.py`)
- GTK / CLI app → User prompts: selects CLI prompts (evidence: `src/gui/AdwApp.py`)
- Option and profiles → Resource paths: uses options directory (evidence: `src/data/OptionStore.py`)
- Program entry → App metadata: uses app metadata (evidence: `src/main.py`)
