A technical overview of the GoodByeDPI GUI codebase — for contributors and anyone curious about how it's built.

The codebase follows three simple rules:

This separation means you can redesign the UI without touching business logic — and vice versa.

GoodByeDPI-GUI/
├── main.py                     ← entry point
├── requirements.txt
├── README.md
├── LICENSE
├── .gitignore
│
├── assets/                     ← visual resources
│   ├── logo.ico
│   └── Screenshot.png
│
├── bin/                        ← runtime binaries & drivers
│   ├── goodbyedpi.exe
│   ├── WinDivert.dll
│   └── WinDivert64.sys
│
└── app/                        ← application package
    ├── __init__.py
    ├── constants.py            ← all app constants & mode presets
    ├── settings.py             ← QSettings wrapper
    ├── utils.py                ← helpers (paths, admin check, versions)
    ├── validator.py            ← custom-arguments validator
    │
    ├── core/                   ← business logic
    │   ├── __init__.py
    │   ├── controller.py       ← wires UI, tray, settings, updater
    │   └── updater.py          ← GitHub release checker (QThread)
    │
    └── ui/                     ← presentation layer
        ├── __init__.py
        ├── main_window.py      ← MainWindow (signals only)
        ├── dialogs.py          ← UpdateDialog, AboutDialog, Args Guide
        ├── widgets.py          ← StatusDot, StatusPill, UptimeChip,
        │                          ModeCard, ModeCardGroup,
        │                          Toast, ToastManager
        ├── theme.py            ← Catppuccin-inspired QSS
        └── tray.py             ← TrayManager (system tray)

• Creates QApplication
• Checks admin privileges — refuses to start if not elevated
• Instantiates AppController and shows the window
• Runs the Qt event loop

• App name, version, author
• GitHub repository info & release URL builder
• Mode presets as NamedTuple (key, title, badge, icon, description, args, tooltip)
• Bundled resource paths (DPI_EXE_REL, LOGO_ICO_REL)

• Thin wrapper around QSettings
• Properties: mode_index, custom_args, geometry
• Uses Windows registry under the hood

• resource_path() — resolves bundled paths for both dev & PyInstaller
• is_admin() — checks via ctypes.windll.shell32.IsUserAnAdmin
• executable_path() — returns EXE path or main.py in dev
• parse_version(), is_newer_version()

• Pure function validate_args(args_str)
• Returns ValidationResult with errors & warnings
• No Qt imports — fully testable standalone
• Knows every GoodbyeDPI flag and cross-flag rules

The heart of the app. Wires everything together:

• Owns MainWindow, TrayManager, UpdateChecker
• Manages QProcess for launching goodbyedpi.exe
• Persists state to AppSettings
• Handles autostart via Windows Task Scheduler
• Displays dialogs (About, Update, Custom Args Help)

Two classes:

• _UpdateWorker(QThread) — scrapes the /releases/latest redirect (GitHub API is avoided because it's blocked in some regions)
• UpdateChecker(QObject) — public API with three signals: update_available(str), up_to_date(), error()

💡 Why scrape instead of using the API? GitHub's api.github.com is blocked in certain countries. Following the redirect of /releases/latest gives us the version number using a domain that's more likely to be reachable.

• Pure presentation — only emits signals
• Signals: start_clicked, stop_clicked, mode_changed(int), custom_args_changed(str), etc.
• Contains zero business logic — the controller decides what happens
• Manages the ToastManager overlay
• Handles smooth window resize when switching modes
• Applies Windows dark title bar via DwmSetWindowAttribute

Custom, reusable widgets:

• UpdateDialog — shows current vs. latest version cards
• AboutDialog — app info, powered-by links, credits
• CustomArgsHelpDialog — tabbed flag guide with live search

• Single global DARK_QSS string
• Catppuccin-inspired palette
• Applied to MainWindow; child widgets inherit

• Owns QSystemTrayIcon and its menu
• Signals: start_requested, stop_requested, exit_requested, restore_requested
• Updates icon tooltip and menu state based on running status

Here's how a user click travels through the app:

┌──────────────────────────────────────────────────────────────┐
│  User clicks "▶ Start"                                       │
└──────────────────────┬───────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────────┐
│  MainWindow.start_clicked  (Signal)                          │
└──────────────────────┬───────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────────┐
│  AppController.start()  (Slot)                               │
│                                                              │
│  1. Reads current mode from window                           │
│  2. Validates custom args (if Custom mode)                   │
│  3. Checks DPI_EXE exists                                    │
│  4. Creates QProcess                                         │
│  5. Emits updates → window.set_running_state(True)           │
│  6. Emits updates → tray.set_running(True)                   │
│  7. Appends log separator                                    │
└──────────────────────────────────────────────────────────────┘

The UI never decides what to do — it just says "the user clicked Start" and the controller figures out the rest.

Controller.start()
    │
    ▼
QProcess.start(goodbyedpi.exe, args)
    │
    ├─── readyReadStandardOutput ───→ window.append_log(text)
    │
    ├─── finished(exit_code) ───────→ _on_process_finished()
    │                                     │
    │                                     ├─→ window.set_running_state(False)
    │                                     ├─→ tray.set_running(False)
    │                                     └─→ process.deleteLater()
    │
    └─── errorOccurred(error) ──────→ _on_process_error()
                                          │
                                          └─→ window.append_log("[error] ...")

Controller.stop()
    │
    ▼
QProcess.kill() + waitForFinished(2000)
    │
    ▼
finished signal fires → same path as natural exit

Say you want to add a "Restart" button next to Start/Stop. Here's the workflow:

In app/ui/main_window.py:

• Add restart_clicked = Signal()
• Create the button, add to layout
• Wire: self.restart_btn.clicked.connect(self.restart_clicked.emit)

In app/core/controller.py:

• Connect: self.window.restart_clicked.connect(self.restart)
• Implement restart(self) slot: call self.stop() then self.start()

In app/ui/theme.py:

• Add QSS for QPushButton#restartBtn

No UI code needs to know how restart works. No core code needs to know the button exists.

Because the UI and core are decoupled, you can test business logic without ever showing a window.

The entire visual style is one QSS string in app/ui/theme.py:

DARK_QSS = """
QMainWindow { background: ...; }
QPushButton#startBtn { background-color: #a6e3a1; ... }
QFrame#modeCard[selected="true"] { border: 1px solid #89b4fa; ... }
..."""

# Applied once at window construction:
self.setStyleSheet(DARK_QSS)

Dynamic states (like a selected mode card) use Qt properties:

# In the widget:
self.setProperty("selected", True)
self.style().unpolish(self)
self.style().polish(self)

QSS then matches via [selected="true"] selector.

utils.resource_path() handles both development and PyInstaller builds:

def resource_path(relative_path: str) -> str:
    if getattr(sys, "frozen", False):
        base_path = sys._MEIPASS        # PyInstaller temp dir
    else:
        base_path = project_root         # parent of app/
    return os.path.join(base_path, relative_path)

This means resource_path("bin/goodbyedpi.exe") works identically whether you're running from source or from a bundled EXE.

Three layers enforce admin:

1. main.py — exits with error dialog if not admin
2. PyInstaller --uac-admin — triggers UAC on launch
3. Task Scheduler — created with /rl highest for autostart

1. Fork the repo
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Follow the UI ↔ Core separation — no business logic in widgets
4. Comment non-obvious code
5. Test manually with python main.py
6. Commit: git commit -m "feat: add amazing feature"
7. Push and open a Pull Request

💡 Prefer Conventional Commits: feat:, fix:, refactor:, docs:, style:.