# Dev notes — assumptions that turned out wrong

Running list so the same mistakes aren't repeated. Add to it whenever reality
contradicts an assumption.

## The GUI does not run on the development Mac (2026-09-07)

The macOS **CommandLineTools** Python 3.9 (`/Library/Developer/CommandLineTools/
.../python3.9`) ships **Tk 8.5.9**. `ttkbootstrap` 1.10.1 requires **Tk 8.6+**.

Symptoms when trying to launch `App()` there:
- `_tkinter.TclError: couldn't recognize image data` (ttkbootstrap's window icon
  is a PNG; Tk 8.5 can't decode it), and
- `_tkinter.TclError: unknown option "-style"` on `ttk.Scrollbar`.

Consequences:
- `app.py` **cannot be smoke-tested through the GUI on this machine.** Logic is
  covered by a non-GUI script (constructs `DataStore`, exercises helpers and the
  worker with monkey-patched paths).
- The **Linux Mint target is unaffected** — its system Tk is 8.6.
- If GUI testing on macOS is ever needed, install a Homebrew
  `python-tk@3.x` / `tcl-tk` combo, or use `pyenv` with `--with-tcltk`.

## `pandas` reads everything as strings by design

`DataStore._load` uses `dtype={...: str}` for `postal_code`, `lat`, `lon`.
Numeric parsing is deliberately deferred to `get_map_data` (`pd.to_numeric(...,
errors="coerce")`). Don't "fix" columns to float on load — blank coordinates and
leading-zero PLZ both depend on the string representation.

## Nominatim query order matters

`geocode_city` returns the **first** hit, trying PLZ-qualified first, then each
region in `GEOCODE_REGIONS`, then a bare `", Germany"`. Reordering changes which
coordinates ambiguous town names resolve to.