Architecture

🏗 Architecture

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

---

🎯 Design Principles

The codebase follows three simple rules:

Principle	Why
UI is pure	Widgets only emit signals. They never perform business logic.
Core is testable	No direct dependency on widgets. Logic can be unit-tested in isolation.
Controller wires everything	A single object connects UI signals to business logic to side-effects.

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

---

📁 Project Layout

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)

---

🧩 Module Responsibilities

📍 main.py — Entry Point

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

📌 app/constants.py

• 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)

⚙️ app/settings.py

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

🛠 app/utils.py

• 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()

✅ app/validator.py

• 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

---

🧠 Core Layer — app/core/

🎛 controller.py — AppController

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)

🔄 updater.py

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.

---

🎨 UI Layer — app/ui/

🖼 main_window.py — MainWindow

• 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

📦 widgets.py

Custom, reusable widgets:

Widget	Purpose
StatusDot	Animated colored dot (pulses when running)
StatusPill	Pill combining dot + label
UptimeChip	Live HH:MM:SS session timer
ModeCard	Single selectable mode card
ModeCardGroup	Radio-style group of ModeCards
Toast	Self-dismissing notification card
ToastManager	Stacks & positions toasts

💬 dialogs.py

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

🎨 theme.py

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

🔔 tray.py — TrayManager

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

---

🔗 Signal Flow

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.

---

🎬 Process Lifecycle

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

---

🧪 Adding a New Feature

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

1. Add UI

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)

2. Add Logic

In app/core/controller.py:

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

3. Style It

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.

---

🧪 Testing Strategy

Layer	How to Test
validator.py	Unit tests — pure function, no Qt needed
utils.py	Unit tests — version parsing, path resolution
core/	Integration — mock the UI, verify signal wiring
ui/	Manual — run python main.py and interact

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

---

🎨 Theme System

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.

---

📦 Bundled Resources

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.

---

🔐 Admin Privileges

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

---

🧭 Where to Go Next

I want to...	Look at
Change the visual style	app/ui/theme.py
Add a button	app/ui/main_window.py + app/core/controller.py
Add a GoodbyeDPI flag	app/validator.py + app/ui/dialogs.py
Tweak update behavior	app/core/updater.py
Add a setting	app/settings.py
Add a mode preset	app/constants.py (append to MODE_PRESETS)

---

🤝 Contributing Code

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:.

---

Ready to build? See Build from Source 🛠

_{Happy hacking 🧑‍💻}