Initial commit

README.md

@@ -1,3 +1,70 @@
 # frontend-app-windows
 
-Windows notification app that pulls messages
+Windows tray app that pulls notifications from the backend and shows them as toasts.
+Clicking a toast opens its link. Requires Windows 10/11 and Python 3.12.
+
+## How it works
+
+- A background thread polls `GET /internal/pull-notifications` every 5 minutes (every 30 s while the server reports `has_more`, with backoff on errors).
+- The newest 5 messages pop up; older ones go silently to the notification bar. One extra toast says how many more are there and whether more are waiting on the server.
+- The API key is stored in Windows Credential Manager.
+
+
+## Setup
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\activate
+pip install -r requirements-dev.txt
+```
+
+## Run from source
+
+```powershell
+$env:NOTIFIER_API_KEY = "your-key"   # or skip: the app asks on first run
+python src\main.py                   # tray app
+python src\main.py --once            # one poll, then exit
+python src\main.py --set-key         # (re)enter the API key
+```
+
+## Test without the real backend
+
+The mock server always returns 10 messages with `has_more: true`.
+
+```powershell
+# terminal 1
+python tools\mock_server.py
+
+# terminal 2
+$env:NOTIFIER_URL = "http://127.0.0.1:8000/internal/pull-notifications"
+$env:NOTIFIER_API_KEY = "dev"        # any value, the mock ignores it
+python src\main.py --once
+```
+
+Without `--once` the tray app polls again after 30 s, because the mock always says `has_more`.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `NOTIFIER_URL` | `https://notifier.gansejunge.com/internal/pull-notifications` | Endpoint |
+| `NOTIFIER_API_KEY` | (Credential Manager) | Overrides the stored key, for development |
+| `NOTIFIER_API_KEY_HEADER` | `X-API-Key` | Header name the backend expects |
+| `NOTIFIER_POLL_SECONDS` | `300` | Normal polling interval |
+
+Other settings (app name, backoff, `has_more` delay) are in `src/config.py`.
+
+## Build the exe
+
+```powershell
+.\build.ps1 -Console   # first build: keeps a console so startup errors are visible
+.\build.ps1            # release build, no console
+```
+
+Output: `dist\MyApp\MyApp.exe`. Ship the whole `dist\MyApp\` folder (it is `--onedir`, not a single file).
+Test the built exe, not just the source: missing PyInstaller imports only show up there.
+
+## Runtime notes
+
+- **Logs:** `%LOCALAPPDATA%\Notifier\app.log`
+- **Tray menu:** Check now, Set API key, Start with Windows (built exe only), Quit.