Why we built a desktop app on local Flask + browser UI instead of PyQt or Electron

When you double-click WP Maintenance Manager, it opens a browser tab — and the entire UI lives inside that tab. No native window is created. It's an unusual structure for a first-time user, and the natural question is: "why a browser?"

That choice was an intentional design decision when building a Python desktop application. Here's the comparison that led to it, and the side effects of the choice.

Four realistic options

For a WordPress maintenance automation tool, four implementation styles were practical:

PyQt was a serious early candidate. A Python-only stack is appealing, but widget styling drifts subtly between OSes, Qt's layout system demands constant attention, and resolving Qt plugins under PyInstaller is fiddly. Dev velocity was not where it needed to be.

Electron is the industry-standard choice for cross-platform UI, with the big benefit that HTML/CSS-based UIs are quick to write. But the distribution is well over 100 MB, and memory consumption is heavy. For a tool that often runs in the background, that overhead is too much to justify.

Why local Flask + browser won

The final structure was Flask (Python's lightweight web framework) + the system browser for UI. The decision rested on three axes:

1. The backend had to be Python anyway

SSH connections via fabric / paramiko, browser automation via playwright, encryption via cryptography — every library at the core of WordPress maintenance lives in the Python ecosystem. Writing the backend in another language wasn't really an option. If Python is already required on the backend, putting the UI in Python too keeps distribution simple.

2. HTML/CSS/JS makes UI iteration fast

Flask renders templates/index.html, and the UI is built with Tailwind CSS and vanilla JS. Anyone with web-development experience can ship features quickly. Learning a new native widget vocabulary every time slows iteration far more than this approach does.

3. Distribution is about 1/3 the size of Electron

By not bundling Chromium, the PyInstaller artifact lands around 50 MB. The same Python codebase and the same templates/ directory power both the macOS .app and the Windows .exe. Almost no per-OS extra work — that was the biggest practical win.

The side effects of using a browser

This structure comes with a tax. The browser tab is the UI. If the user closes that tab, the app is still running, but there's no way to reach it. Double-clicking the app again to reopen it doesn't help, because macOS LaunchServices sees "this app is already running" and just refocuses it, without opening a new browser tab.

Fixing this required a heartbeat-based liveness check combined with a self-clobbering lockfile. (Details in when a macOS desktop app refuses to restart.)

There are other side effects too: a fixed port is occupied (so port-collision detection is needed), browser private mode breaks the login session, and so on. None of these would have existed with a native window.

Reflection — structure choice is requirement-dependent

"Local Flask + browser UI" is not a universal best choice. For apps that lean heavily on native UI components (notification center, menu-bar residency, keychain integration), or where startup happens frequently in offline-only contexts, PyQt or Native make more sense.

But under the constraints WordPress maintenance automation actually had — backend-heavy, dashboard-style UI, small distribution, mandatory two-OS support — Flask + browser was the right balance. We optimized for dev velocity and distribution size, accepting other trade-offs.

The side effects need separate, careful handling. Even so, the structure has more than paid for itself across the lifetime of the project.