NotifyPulse — Multi-Profile Block Architecture

NotifyPulse is a Windows notification engine built around Usecases and Blocks. Each usecase is an isolated profile with its own folder, enabled blocks, and notification list. A tray app runs quietly in the background; a local web UI lets you manage everything.

---

Folder structure

NotifyPulse/
├── notifier.py          ← Main backend
├── requirements.txt
├── build.bat
├── ui/
│   └── index.html       ← Desktop Web UI (usecase manager)
└── pwa/
    ├── index.html       ← Mobile PWA (splash + selector + wallpaper)
    ├── manifest.json
    └── sw.js

Config and assets live in %APPDATA%\Roaming\NotifyPulse\:

NotifyPulse\
├── usecases.json        ← All usecase definitions
├── settings.json        ← Global settings
│
├── icon.png             ← Tray icon  ──────────────────────────────────┐
│                           Shown in the Windows system tray.           │
│                           Recommended: 256×256 px, PNG with           │  App Icons
│                           transparency. Falls back to a default       │
│                           coloured circle if missing.                 │
│                                                                       │
├── icon.ico             ← Window / taskbar icon (optional)             │
│                           Used when the app is compiled to .exe.      │
│                           Recommended: multi-size ICO (16/32/48/256). │
│                           If absent, icon.png is used instead.        ┘
│
├── main.png             ← PWA splash background  ──────────────────────┐
│                           Full-screen background shown on the phone   │
│                           PWA while it loads. Recommended: your       │  PWA Assets
│                           phone's native resolution (e.g. 1170×2532   │
│                           for iPhone 14). JPEG is also accepted.      ┘
│
└── usecases\
    ├── my_profile_abc123\
    │   ├── wallpapers\  ← Desktop wallpapers for this usecase
    │   ├── overlay\     ← Overlay images for this usecase
    │   └── mobile\      ← Mobile wallpapers for this usecase (pushed via PWA)
    └── ...

Placing app icons

File	Where it shows	Recommended size	Notes
icon.png	Windows system tray	256 × 256 px	PNG, transparent background
icon.ico	Taskbar / .exe (compiled)	Multi-size ICO	16, 32, 48, 256 px layers
main.png	PWA splash screen	Phone native res	JPEG also accepted

Drop these files into %APPDATA%\Roaming\NotifyPulse\ and restart the app. No config change needed — the app picks them up automatically.

---

Quick start

pip install -r requirements.txt
python notifier.py

Or build an .exe (bundles everything, no Python required to run):

build.bat

---

Blocks

Each usecase can enable any combination of blocks:

Block	What it does
🔔 Notifications	Random & scheduled Windows toast notifications
🖼️ Wallpaper	Changes desktop wallpaper from usecase's wallpapers\ folder
✨ Overlay	Fullscreen image overlay from usecase's overlay\ folder
⏱️ Timer	Enables time-triggered entries (HH:MM syntax)
📱 Mobile Wallpaper	Pushes wallpapers to phone via PWA from usecase's mobile\ folder

---

Creating a Usecase

Desktop UI → Usecases → + New Usecase

1. Give it a name and accent color
2. Check the blocks you need
3. Set the min/max notification interval (in minutes)
4. Add notification entries (supports | % weights and | HH:MM schedules)
5. Click ▶ Activate to start using it
6. Click 📁 Folder to open the usecase folder and drop in your images

---

notifications.txt syntax (per usecase)

# Weighted random
Take a break!             | 35%
Drink water!              | 30%
change.wallpaper          | 20%
show.overlay              | 15%
show.overlay.10           | 10%    ← overlay for 10 seconds
change.wallpaper.mobile             ← push to phone PWA

# Scheduled (needs Timer block)
Morning standup           | 09:00
End of day                | 17:30

---

Settings reference

All settings are saved to %APPDATA%\Roaming\NotifyPulse\settings.json and editable in the desktop UI under the Settings tab.

General

Setting	Default	Description
app_name	"NotifyPulse"	Name shown in the header before any usecase is selected
hotkey	"F13"	Global hotkey to pause / resume
log_max_entries	100	How many log lines to keep in memory
startup_toast	true	Show a toast notification when the app starts
notify_sound	true	Play sound with toast notifications
auto_open_browser	true	Open the web UI automatically on start
minimize_to_tray	true	Closing the window hides to tray instead of quitting
run_on_startup	false	Register NotifyPulse in Windows startup
confirm_delete	true	Show a confirmation dialog before deleting a usecase
entry_display_mode	"percent"	Default display for entry weights: percent or chance

Notifications

Setting	Default	Description
notification_duration	5	How many seconds a toast stays on screen (1–30)

Overlay

Setting	Default	Description
overlay_duration	6	Default overlay display time in seconds
overlay_opacity	0.4	Overlay transparency (0.05 – 1.0)
overlay_stretch	false	Stretch to fill (true) or letterbox-fit (false)
overlay_monitor	0	Which monitor: 0 = primary, -1 = all, 1/2/3 = specific

Wallpaper

Setting	Default	Description
wallpaper_fit	"fill"	How the image is scaled: fill · fit · stretch · center · tile

Network / PWA

Setting	Default	Description
web_port	5000	Port for the web UI and PWA

---

PWA Splash Screen

Drop a main.png (or .jpg) into %APPDATA%\NotifyPulse\ to use it as the full-screen background when the PWA first loads on your phone.

---

PWA Usage

1. Start NotifyPulse on your PC
2. On your phone, open: http://<your-pc-ip>:5000/pwa
3. iOS: Share → Add to Home Screen
4. Android: ⋮ → Install App

The PWA shows your splash screen, then a list of usecases to switch between. Selecting one activates that usecase and shows the wallpaper receiver if the Mobile Wallpaper block is enabled.

---

API Reference

Method	Endpoint	Description
GET	/api/usecases	List all usecases + blocks
POST	/api/usecases	Create a usecase
PUT	/api/usecases/:id	Update a usecase
DELETE	/api/usecases/:id	Delete a usecase
POST	/api/usecases/:id/activate	Switch active usecase
POST	/api/usecases/:id/open_folder	Open usecase folder in Explorer
GET	/api/state	Full app state
POST	/api/pause	Toggle pause
POST	/api/fire_now	Fire a random entry immediately
GET/POST	/api/settings	Read / update global settings
GET	/api/log	Event log
POST	/api/pwa/ping	PWA heartbeat
GET	/api/pwa/app_name	App info + usecase list for PWA
GET	/api/pwa/splash_image	Serve main.png as base64
GET	/api/pwa/wallpaper	Poll for pending mobile wallpaper
POST	/api/pwa/trigger_wallpaper	Request a new wallpaper push
POST	/api/pwa/activate_usecase	Activate a usecase from the PWA