Desktop Local App Lessons

A desktop app has three different kinds of state:

visible state:
  what the user sees now

durable state:
  local database, config, user files, saved records

runtime state:
  workers, timers, browser sessions, sockets, caches, queues

A bug often happens when these are mixed.

Example:

UI shows "updated"
database write failed
worker is still running
timer will retry in the background

The user thinks the action completed, but the runtime disagrees.

The product should make state visible:

current file/database
last import status
active worker count
last parser error
next scheduled run
cache/log locations
shutdown status

The desktop lesson:

If local state exists, the user should be able to inspect it.
If background work exists, the user should know whether it is running.
If generated files exist, the user should be able to delete them.

A worker should not just be a background function.

It needs a contract:

Bad worker:

worker reads current UI fields while running
worker mutates widgets directly
worker raises generic exception
worker cannot be cancelled

Better worker:

UI gathers current form values
UI creates immutable request
worker processes request
worker emits progress/result/error
UI thread applies result if job is still current

Stale result protection:

current_job_id = 42
result.job_id = 41

if result.job_id != current_job_id:
  ignore result

This matters for:

search filters
scraper runs
imports
dashboards
background refresh
browser automation
selection detail panels

Late results are normal in concurrent apps. Treat them as expected.

Sorting 100,000 rows on every keystroke is bad.

Better flow:

flowchart LR
  A[User types filter] --> B[Debounce]
  B --> C[Worker computes matching row ids]
  C --> D[Model swaps visible mapping]
  D --> E[View repaints]

For small tables, a proxy model may be enough. For larger datasets, use an explicit visible-row mapping:

all_rows = source records
visible_rows = row ids matching current filter

The model maps:

source_row = visible_rows[view_row]

This avoids copying full records around.

Filter state should be visible:

showing 1,284 of 92,000 records
filter: status=open, source=remote, text="python"

Long-running filters should be cancellable:

new filter typed -> cancel old filter job

Otherwise, old filter results can overwrite newer user intent.

Parsers drift.

Examples:

job site changes HTML
bank changes SMS format
chat export format changes
price page moves value into script tag
CVE feed changes schema

Parser health should be product state.

Show:

last successful parse
last failed parse
parse version
records found
records rejected
error sample
next retry
source freshness

Bad UX:

empty result list

Better UX:

Parser failed: salary field selector matched 0 items.
Last good run: yesterday.
Source page changed or parser needs update.

Parser record shape:

source_id
parser_version
last_success_at
last_failure_at
last_error_kind
last_error_sample
records_seen
records_accepted
records_rejected

The user should never have to guess whether there are no results or the parser broke.

Money apps need deterministic imports before AI suggestions.

Correct pipeline:

CSV/bank export
-> parse preview
-> normalize date/amount/currency
-> detect duplicate
-> user confirms
-> create import batch
-> optional category suggestions

AI can suggest categories later:

merchant: "Metro Cafe"
suggested category: Food
confidence: medium

But AI should not replace import correctness:

amount
date
currency
account
duplicate status

These are structured facts. They should be parsed and validated with deterministic code.

Failure examples:

The design goal:

the user can explain every transaction's source

A price tracker is a scheduler plus parser plus alert system.

flowchart LR
  A[Tracked item] --> B[Schedule check]
  B --> C[Fetch page or API]
  C --> D[Parse price]
  D --> E[Store history]
  E --> F{Threshold crossed?}
  F -- yes --> G[Notify user]
  F -- no --> H[Update last checked]

UI fields:

last checked
next check
last error
current price
target price
history chart
notification status
parser/source health

No hidden infinite loops.

No stray browser/helper processes after exit.

No fake precision:

unknown price
parser failed
source blocked
network unavailable

These are different states.

A local Kanban app can use simple JSON or SQLite, but it needs state rules.

Questions to define:

Simple storage is fine if recovery behavior is explicit.

Bad:

autosave failed silently

Better:

Autosave failed: permission denied.
Board has unsaved changes.
Save As...

For small productivity tools, data loss is the worst bug.

Tray tools look small but run for long sessions.

They need:

single-instance behavior
clear running/stopped state
visible logs
settings window
quit action
clean shutdown

If a tray app starts a server:

menu shows server status
menu has stop server action
quit stops server
startup does not silently expose port

Small does not mean careless.

Tray app hazards:

orphan process
hidden port
stale lock file
config path unknown
logs hidden
autostart hard to disable

The tray menu should answer:

what is running?
where is config?
where are logs?
how do I stop it?

PyQt model/view is useful when the app has:

native widgets
large tables
dialogs
menus
OS integration
signals/slots

egui-style immediate mode is useful when:

state is compact
rendering is rebuilt from state every frame
you want explicit state structs
layout is tightly controlled

Different style, same rule:

do not do heavy work during rendering

In PyQt:

do not block data()
do not block paintEvent()
do not block selection handlers

In egui:

do not block update()
do not recompute expensive tables every frame
do not run network/file work in the frame loop

Immediate mode does not remove runtime concerns. It just makes state ownership more explicit.

Generated data should be separated by risk.

Examples:

Do not call all of these “clean up.”

They are different actions.

Good cleanup UI:

category
size
path
purpose
delete consequence
action button
last modified

Generated files should be deletable from the GUI when the app created them.

Primary user data needs stronger confirmation than caches.

Desktop apps need logs because failures happen outside request/response boundaries.

Log boundaries:

startup
settings load/save
import start/finish/failure
parser failure
scheduler run
worker cancellation
browser session start/stop
database migration
shutdown

Logs should not contain secrets by default.

Examples to redact:

API tokens
cookies
auth headers
full bank transaction exports
private chat content
local-only sensitive paths when exported

The app should expose logs:

open log file
copy diagnostic summary
delete logs
export support bundle with redaction

A simple desktop runtime shape:

UI:
  views, actions, dialogs, status

model/store:
  local records, settings, generated data metadata

workers:
  imports, scans, parsing, network, cleanup

scheduler:
  next run, last run, retry state

parser:
  versioned extraction logic, health report

storage governance:
  size, location, delete/rebuild actions

Keep this direct. Do not create wrapper layers that only forward calls.

Better small design:

main window
table model
storage functions
worker jobs
parser functions
scheduler state

Worse design:

Controller -> Service -> Manager -> Provider -> Client

If a layer adds no behavior, remove it.

Worker jobs are used because desktop UIs freeze when imports, parsing, scraping, database work, and browser automation run on the main thread.

Virtualized model/view tables are used because large datasets should not become thousands of widgets. The UI should render visible rows and keep expensive work out of data() and paint paths.

Import previews and batch IDs are used because local records need provenance. If a CSV or chat import goes wrong, the user should be able to inspect, rollback, or delete the exact batch.

Parser health is used because scrapers and importers drift. An empty result is not enough information; the product must distinguish “nothing found” from “parser failed.”

Scheduler visibility is used because polling without state becomes hidden behavior. The user should know last run, next run, last error, and whether data is stale.

Generated-storage cleanup is used because local apps create databases, caches, logs, browser profiles, exports, and temp files. If the app creates it, the app should expose it.

Clean shutdown is used because local desktop tools often start workers, timers, browser sessions, or servers. Closing the window should not leave the runtime alive.