# 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

```bat
pip install -r requirements.txt
python notifier.py
```

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

```bat
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 |