crowd-funder-for-time-pwa/doc/notification-system-plan.md

# TimeSafari Notification System — Strategic Plan

**Status:** 🚀 Active plan  
**Date:** 2025-09-05T05:09Z (UTC)  
**Author:** Matthew Raymer  
**Scope:** v1 (in‑app orchestrator) now; path to v2 (native plugin) next  
**Goal:** We **will deliver** 1..M local notifications/day with content **prefetched** so messages **will display offline**. We **will support** online‑first (API→DB→Schedule) with offline‑first fallback. The system **will enhance** TimeSafari's community-building mission by keeping users connected to gratitude, gifts, and collaborative projects through timely, relevant notifications.

> **Implementation Details:** See `notification-system-implementation.md` for detailed code, database schemas, and integration specifics.  
> **Canonical Ownership:** This document owns Goals, Tenets, Platform behaviors, Acceptance criteria, and Test cases.

---

## 1) Versioning & Intent

- **v1 (In‑App Orchestrator):** We **will implement** multi‑daily local notifications, online/offline flows, templating, SQLite persistence, and eventing **inside the app** using Capacitor Local Notifications.  
- **v2 (Plugin):** We **will extract** adapters to a Capacitor/Native plugin to gain native schedulers (WorkManager/AlarmManager; BGTask+UNUserNotificationCenter), native HTTP, and native SQLite **with the same TypeScript API**.

> We **will retain** the existing web push + Service Worker foundation; the system **will add** reliable local scheduling on mobile and a unified API across platforms.

---

## 2) Design Tenets

- **Reliability:** OS‑level delivery once scheduled; no reliance on JS being alive at fire time.  
- **Freshness:** Prefer online‑first within a short prefetch window; degrade gracefully to cached content with TTL.  
- **Extractable:** Clean interfaces (Scheduler, DataStore, Callbacks) so v2 **will swap** adapters without API changes.  
- **Simplicity:** One‑shot notifications per slot; rolling window scheduling to respect platform caps.  
- **Observability:** Persist deliveries and errors; surface minimal metrics; enable ACKs.
- **Privacy-First:** Follow TimeSafari's privacy-preserving architecture; user-controlled visibility and data sovereignty.
- **Community-Focused:** Enhance TimeSafari's mission of connecting people through gratitude, gifts, and collaborative projects.

---

## 3) Architecture Overview

```
Application (Vue/TS)
 ├─ NotificationOrchestrator (core state)
 │   ├─ Scheduler (adapter)
 │   ├─ DataStore (adapter)
 │   └─ Callbacks (adapter)
 └─ UI (settings, status)

Adapters
 ├─ V1: SchedulerCapacitor, DataStoreSqlite, CallbacksHttp
 └─ V2: SchedulerNative, DataStoreNativeSqlite, CallbacksNativeHttp

Platform
 ├─ iOS/Android: LocalNotifications (+ native bridges later)
 ├─ Web: Service Worker + Push (kept)
 └─ Electron: OS notifications (thin adapter)
```

**Execution modes (concise):**  
- **Online‑First:** wake near slot → fetch (ETag, timeout) → persist → schedule; on failure → Offline‑First.  
- **Offline‑First:** read last good payload from SQLite; if beyond TTL → skip notification (no retry).

---

## 4) Public API (Shared by v1 & v2)

```ts
export type NotificationTime = { hour: number; minute: number }; // local wall-clock
export type SlotId = string; // Format: "HHmm" (e.g., "0800", "1200", "1800") - stable across TZ changes

export type FetchSpec = {
  method: 'GET'|'POST';
  url: string;
  headers?: Record<string,string>;
  bodyJson?: Record<string,unknown>;
  timeoutMs?: number;
};

export type CallbackProfile = {
  fetchContent: FetchSpec;
  ackDelivery?: Omit<FetchSpec,'bodyJson'|'timeoutMs'>;
  reportError?: Omit<FetchSpec,'bodyJson'|'timeoutMs'>;
  heartbeat?: Omit<FetchSpec,'bodyJson'> & { intervalMinutes?: number };
};

export type ConfigureOptions = {
  times: NotificationTime[];                  // 1..M daily
  timezone?: string;                          // Default: system timezone
  ttlSeconds?: number;                        // Default: 86400 (24h)
  prefetchLeadMinutes?: number;               // Default: 20
  storage: 'shared'|'private';               // Required
  contentTemplate: { title: string; body: string }; // Required
  callbackProfile?: CallbackProfile;          // Optional
};

export interface MultiDailyNotification {
  requestPermissions(): Promise<void>;
  configure(o: ConfigureOptions): Promise<void>;
  runFullPipelineNow(): Promise<void>;        // API→DB→Schedule (today's remaining)
  deliverStoredNow(slotId?: SlotId): Promise<void>; // 60s cooldown guard
  reschedule(): Promise<void>;
  getState(): Promise<{
    nextOccurrences: Array<{ slotId: SlotId; when: string }>; // ISO
    lastFetchAt?: string; lastDeliveryAt?: string;
    pendingCount: number; exactAlarmCapable?: boolean;
  }>;
}
```

> **Storage semantics:** `'shared'` = app DB; `'private'` = plugin-owned/native DB (v2). (No functional difference in v1.)

> **Slot Identity & Scheduling Policy**
> • **SlotId** uses canonical `HHmm` and remains stable across timezone changes.
> • **Lead window:** default `prefetchLeadMinutes = 20`; no retries once inside the lead.
> • **TTL policy:** When offline and content is beyond TTL, **we will skip** the notification (no "(cached)" suffix).
> • **Idempotency:** Duplicate "scheduled" deliveries are prevented by a unique index on `(slot_id, fire_at, status='scheduled')`.
> • **Time handling:** Slots will follow **local wall-clock** time across TZ/DST; `slotId=HHmm` stays constant and we will **recompute fire times** on offset change.

---

## 5) Data Model & Retention (SQLite)

**Tables:** `notif_contents`, `notif_deliveries`, `notif_config`

**Retention:** We **will keep** ~14 days of contents/deliveries (configurable) and **will prune** via a simple daily job that runs on app start/resume. We **will prune** daily but **will not** VACUUM by default on mobile; disk compaction is deferred.

**Payload handling:** We **will template** `{title, body}` **before** scheduling; we **will not** mutate at delivery time.

---

## 6) Scheduling Policy & Slot Math

- **One‑shot per slot** per day (non‑repeating).  
- **Rolling window:** today's remaining slots; seed tomorrow where platform limits allow. v1 will schedule **the next occurrence per slot** by default; a **configurable depth** (0=today, 1=today+tomorrow) may be enabled as long as the iOS pending cap is respected.
- **TZ/DST safe:** We **will recompute** local wall‑times on app resume and whenever timezone/offset changes; then **reschedule**.  
- **Android exactness:** If exact alarms are unavailable or denied, we **will use** `setWindow` semantics via the scheduler adapter.  
- **iOS pending cap:** We **will keep** pending locals within typical caps (~64) by limiting the window and canceling/re‑arming as needed.
- **Electron rolling window:** On Electron we **will schedule** the **next occurrence per slot** by default; depth (today+tomorrow) **will be** enabled only when auto-launch is on, to avoid drift while the app is closed.

---

## 7) Platform Essentials

**iOS**  
- Local notifications **will** fire without background runtime once scheduled. NSE **will not** mutate locals; delivery-time enrichment requires remote push (future).
- **Category ID**: `TS_DAILY` with default `OPEN` action
- **Background budget** is short and OS‑managed; any prefetch work **will complete** promptly.
- **Mobile local notifications will route via action listeners (not the service worker)**.

**Android**  
- Exact alarms on **API 31+** may require `SCHEDULE_EXACT_ALARM`. If exact access is missing on API 31+, we will use a **windowed trigger (default ±10m)** and surface a settings deep-link.
- **We will deep-link users to the exact-alarm settings when we detect denials.**
- **Channel defaults**: ID `timesafari.daily`, name "TimeSafari Daily", importance=high (IDs never change)
- Receivers for reboot/time change **will be handled** by v2 (plugin); in v1, re‑arming **will occur** on app start/resume.
- **Mobile local notifications will route via action listeners (not the service worker)**.

**Web**  
- Requires registered Service Worker + permission; can deliver with browser closed. **Web will not offline-schedule**.
- Service worker click handlers apply to **web push only**; local notifications on mobile do **not** pass through the SW.
- SW examples use `/sw.js` as a placeholder; **wire this to your actual build output path** (e.g., `sw_scripts/notification-click.js` or your combined bundle).
- **Note**: Service workers are **intentionally disabled** in Electron (`src/main.electron.ts`) and web uses VitePWA plugin for minimal implementation.

**Electron**  
- We **will use** native OS notifications with **best-effort scheduling while the app is running**; true background scheduling will be addressed in v2 (native bridges).

**Electron delivery strategy (v1 reality + v2 path)**  
We **will deliver** desktop notifications while the Electron app is running. True **background scheduling when the app is closed** is **out of scope for v1** and **will be addressed** in v2 via native bridges. We **will adopt** one of the following options (in order of fit to our codebase):

**In-app scheduler + auto-launch (recommended now):** Keep the orchestrator in the main process, **start on login** (tray app, hidden window), and use the **Electron `Notification` API** for delivery. This requires no new OS services and aligns with our PlatformServiceFactory/mixin patterns.

**Policy (v1):** If the app is **not running**, Electron will **not** deliver scheduled locals. With **auto-launch enabled**, we **will achieve** near-mobile parity while respecting OS sleep/idle behavior.

**UX notes:** On Windows we **will set** `appUserModelId` so toasts are attributed correctly; on macOS we **will request** notification permission on first use.

**Prerequisites:** We **will require** Node 18+ (global `fetch`) or we **will polyfill** via `undici` for content fetching in the main process.

---

## 8) Template Engine Contract

**Supported tokens:** `{{headline}}`, `{{summary}}`, `{{date}}` (YYYY-MM-DD), `{{time}}` (HH:MM).  
**Escaping:** HTML-escape all injected values.  
**Limits:** Title ≤ 50 chars; Body ≤ 200 chars; truncate with ellipsis.  
**Fallback:** Missing token → `"[Content]"`.  
**Mutation:** We **will** render templates **before** scheduling; no mutation at delivery time on iOS locals.

## 9) Integration with Existing TimeSafari Infrastructure

**Database:** We **will integrate** with existing migration system in `src/db-sql/migration.ts` following the established `MIGRATIONS` array pattern  
**Settings:** We **will extend** existing Settings type in `src/db/tables/settings.ts` following the established type extension pattern  
**Platform Service:** We **will leverage** existing PlatformServiceMixin database utilities following the established mixin pattern  
**Service Factory:** We **will follow** the existing `PlatformServiceFactory` singleton pattern for notification service creation  
**Capacitor:** We **will integrate** with existing deep link system in `src/main.capacitor.ts` following the established initialization pattern  
**Service Worker:** We **will extend** existing service worker infrastructure following the established `sw_scripts/` pattern (Note: Service workers are intentionally disabled in Electron and have minimal web implementation via VitePWA plugin)  
**API:** We **will use** existing error handling from `src/services/api.ts` following the established `handleApiError` pattern  
**Logging:** We **will use** existing logger from `src/utils/logger` following the established logging patterns  
**Platform Detection:** We **will use** existing `process.env.VITE_PLATFORM` patterns (`web`, `capacitor`, `electron`)  
**Vue Architecture:** We **will follow** Vue 3 + vue-facing-decorator patterns for component integration (Note: The existing `useNotifications` composable in `src/composables/useNotifications.ts` is currently stub functions with eslint-disable comments and needs implementation)  
**State Management:** We **will integrate** with existing settings system via `PlatformServiceMixin.$saveSettings()` for notification preferences (Note: TimeSafari uses PlatformServiceMixin for all state management, not Pinia stores)  
**Identity System:** We **will integrate** with existing `did:ethr:` (Ethereum-based DID) system for user context  
**Testing:** We **will follow** Playwright E2E testing patterns established in TimeSafari  
**Database Architecture:** We **will support** platform-specific database backends:
- **Web**: Absurd SQL (SQLite via IndexedDB) via `WebPlatformService` with worker pattern
- **Capacitor**: Native SQLite via `CapacitorPlatformService` 
- **Electron**: Native SQLite via `ElectronPlatformService` (extends CapacitorPlatformService)  

---

## 10) Error Taxonomy & Telemetry

**Error Codes:** `FETCH_TIMEOUT`, `ETAG_NOT_MODIFIED`, `SCHEDULE_DENIED`, `EXACT_ALARM_MISSING`, `STORAGE_BUSY`, `TEMPLATE_MISSING_TOKEN`, `PERMISSION_DENIED`.

**Event Envelope:** `code, slotId, whenMs, attempt, networkState, tzOffset, appState, timestamp`.

---

## 11) Permission UX & Channels/Categories

- We **will request** notification permission **after** user intent (e.g., settings screen), not on first render.  
- **Android:** We **will create** a stable channel ID (e.g., `timesafari.daily`) and **will set** importance appropriately.  
- **iOS:** We **will register** categories for optional actions; grouping may use `threadIdentifier` per slot/day.

---

## 12) Eventing & Telemetry

### Error Taxonomy
**Finite error code set:**
- `FETCH_TIMEOUT` - Network request exceeded timeout
- `ETAG_NOT_MODIFIED` - Server returned 304 (expected)
- `SCHEDULE_DENIED` - OS denied notification scheduling
- `EXACT_ALARM_MISSING` - Android exact alarm permission absent
- `STORAGE_BUSY` - Database locked or unavailable
- `TEMPLATE_MISSING_TOKEN` - Required template variable not found
- `PERMISSION_DENIED` - User denied notification permissions

### Event Logging Envelope
```ts
{
  code: string,           // Error code from taxonomy
  slotId: string,         // Affected slot
  whenMs: number,         // Scheduled time
  attempt: number,        // Retry attempt (1-based)
  networkState: string,   // 'online' | 'offline'
  tzOffset: number,       // Current timezone offset
  appState: string,       // 'foreground' | 'background' | 'killed'
  timestamp: number       // UTC timestamp
}
```

### ACK Payload Format
```ts
{
  slotId: string,
  fireAt: number,         // Scheduled time
  deliveredAt: number,    // Actual delivery time
  deviceTz: string,       // Device timezone
  appVersion: string,     // App version
  buildId: string         // Build identifier
}
```

- **Event queue (v1):** In-memory queue for `delivery`, `error`, `heartbeat` events. Background/native work **will enqueue**; foreground **will drain** and publish to the UI. **v2 will migrate** to SQLite-backed queue for persistence.  
- **Callbacks (optional):** `ackDelivery`, `reportError`, `heartbeat` **will post** to server endpoints when configured.  
- **Minimal metrics:** pending count, last fetch, last delivery, next occurrences.

---

## 13) Feature Flags & Config

### Feature Flags Table
| Flag | Default | Description | Location |
|------|---------|-------------|----------|
| `scheduler` | `'capacitor'` | Scheduler implementation | `notif_config` table |
| `mode` | `'auto'` | Online-first inside lead, else offline-first | `notif_config` table |
| `prefetchLeadMinutes` | `20` | Lead time for prefetch attempts | `notif_config` table |
| `ttlSeconds` | `86400` | Content staleness threshold (24h) | `notif_config` table |
| `iosCategoryIdentifier` | `'TS_DAILY'` | iOS notification category | `notif_config` table |
| `androidChannelId` | `'timesafari.daily'` | Android channel ID (never changes) | `notif_config` table |

**Storage:** Feature flags **will reside** in `notif_config` table as key-value pairs, separate from user settings.

---

## 14) Acceptance (Definition of Done) → Test Cases

### Explicit Test Checks
- **App killed → locals fire**: Configure slots at 8:00, 12:00, 18:00; kill app; verify notifications fire at each slot on iOS/Android
- **ETag 304 path**: Server returns 304 → keep previous content; locals fire with cached payload
- **ETag 200 path**: Server returns 200 → update content and re-arm locals with fresh payload
- **Offline + beyond TTL**: When offline and content > 24h old → skip notification (no "(cached)" suffix)
- **iOS pending cap**: Respect ~64 pending limit; cancel/re-arm as needed within rolling window
- **Exact-alarm denied**: Android permission absent → windowed schedule (±10m) activates; UI shows fallback hint
- **Permissions disabled** → we will record `SCHEDULE_DENIED` and refrain from queuing locals.
- **Window fallback** → when exact alarm is absent on Android, verify target fires within **±10m** of slot time (document as an E2E expectation).
- **Timezone change**: On TZ/DST change → recompute wall-clock times; cancel & re-arm all slots
- **Lead window respect**: No retries attempted once inside 20min lead window
- **Idempotency**: Multiple `runFullPipelineNow()` calls don't create duplicate scheduled deliveries
- **Cooldown guard**: `deliverStoredNow()` has 60s cooldown to prevent double-firing

### Electron-Specific Test Checks
- **Electron running (tray or window) → notifications fire** at configured slots using Electron `Notification`
- **Electron not running →** no delivery (documented limitation for v1)
- **Start on Login enabled →** after reboot + login, orchestrator **will re-arm** slots and deliver
- **Template limits honored** (Title ≤ 50, Body ≤ 200) on Electron notifications
- **SW scope** not used for Electron (click handlers are **web only**)
- **Windows appUserModelId** set correctly for toast attribution
- **macOS notification permission** requested on first use

---

## 15) Test Matrix (Essentials)

- **Android:** exact vs inexact branch, Doze/App Standby behavior, reboot/time change, permission denial path, deep‑link to exact‑alarm settings.  
- **iOS:** BG fetch budget limits, pending cap windowing, local notification delivery with app terminated, category actions.  
- **Web:** SW lifecycle, push delivery with app closed, click handling, no offline scheduling.  
- **Cross‑cutting:** ETag/304 behavior, TTL policy, templating correctness, event queue drain, SQLite retention job.

---

## 16) Migration & Rollout Notes

- We **will keep** existing web push flows intact.  
- We **will introduce** the orchestrator behind a feature flag, initially with a small number of slots.  
- We **will migrate** settings to accept multiple times per day.  
- We **will document** platform caveats inside user‑visible settings (e.g., Android exact alarms, iOS cap).

---

## 17) Security & Privacy

- Tokens **will reside** in Keystore/Keychain (mobile) and **will be injected** at request time; they **will not** be stored in SQLite.  
- Optionally, SQLCipher at rest for mobile; redaction of PII in logs; payload size caps.  
- Content **will be** minimal (title/body); sensitive data **will not be** embedded.

---

## 18) Non‑Goals (Now)

- Complex action sets and rich media on locals (kept minimal).  
- Delivery‑time mutation of local notifications on iOS (NSE is for remote).  
- Full analytics pipeline (future enhancement).

---

## 19) Cross-Doc Sync Hygiene

### Canonical Ownership
- **This document (Plan)**: Canonical for Goals, Tenets, Platform behaviors, Acceptance criteria, Test cases
- **Implementation document**: Canonical for API definitions, Database schemas, Adapter implementations, Code examples

### PR Checklist
When changing notification system behavior, update both documents:
- [ ] **API changes**: Update types/interfaces in both Plan §4 and Implementation §3
- [ ] **Schema changes**: Update Plan §5 and Implementation §2  
- [ ] **Slot/TTL changes**: Update Plan §4 semantics and Implementation §6 logic
- [ ] **Template changes**: Update Plan §9 contract and Implementation examples
- [ ] **Error codes**: Update Plan §11 taxonomy and Implementation error handling

### Synchronization Points
- **API code blocks**: Must be identical between Plan §4 and Implementation §3 (Public API (Shared))
- **Feature flags**: Must match between Plan §12 table and Implementation defaults
- **Test cases**: Plan §13 acceptance criteria must align with Implementation test examples
- **Slot/TTL/Lead policies**: Must be identical between Plan §4 policy and Implementation §3 policy

---

## 21) Privacy & Security Alignment

### Privacy-First Architecture
- **User-Controlled Visibility:** Notification preferences **will be** user-controlled with explicit opt-in/opt-out
- **Data Sovereignty:** All notification data **will reside** on user's device; no external tracking or analytics
- **Minimal Data Collection:** We **will collect** only essential data for notification delivery (slot times, content templates)
- **DID Integration:** Notifications **will be** associated with user's Decentralized Identifier (DID) for privacy-preserving identity

### Security Considerations
- **Content Encryption:** Sensitive notification content **will be** encrypted at rest using device keystore
- **Secure Transmission:** All API calls **will use** HTTPS with proper certificate validation
- **Input Validation:** All notification content **will be** validated and sanitized before storage
- **Access Control:** Notification settings **will be** protected by user authentication

### Compliance with TimeSafari Principles
- **Privacy-Preserving:** Follows TimeSafari's privacy-preserving claims architecture
- **User Agency:** Users maintain full control over their notification experience
- **Transparency:** Clear communication about what data is collected and how it's used
- **Minimal Footprint:** Notification system **will have** minimal impact on user privacy

---

## 23) Platform-Specific Implementation Details

### Web Platform (`VITE_PLATFORM=web`)
- **Database:** Uses Absurd SQL (SQLite via IndexedDB) via `WebPlatformService` with worker pattern
- **Notifications:** Web push notifications via Service Worker (minimal implementation)
- **Local Scheduling:** **Not supported** - web cannot schedule local notifications offline
- **API Integration:** Direct HTTP calls for content fetching
- **Storage:** Notification preferences stored in Absurd SQL database
- **Testing:** Playwright E2E tests run on web platform

### Capacitor Platform (`VITE_PLATFORM=capacitor`)
- **Database:** Uses native SQLite via `CapacitorPlatformService`
- **Notifications:** Local notifications via `@capacitor/local-notifications`
- **Local Scheduling:** **Fully supported** - OS-level notification scheduling
- **API Integration:** HTTP calls with mobile-optimized timeouts and retry logic
- **Storage:** Notification preferences stored in native SQLite database
- **Testing:** Playwright E2E tests run on mobile devices (Android/iOS)

### Electron Platform (`VITE_PLATFORM=electron`)
- **Database:** Uses native SQLite via `ElectronPlatformService` (extends CapacitorPlatformService)
- **Notifications:** OS-level notifications via Electron's notification API
- **Local Scheduling:** **Supported** - desktop OS notification scheduling
- **API Integration:** Same as Capacitor platform
- **Storage:** Same as Capacitor platform (via inherited service)
- **Testing:** Same as Capacitor platform

### Cross-Platform Considerations
- **Feature Detection:** Use `process.env.VITE_PLATFORM` for platform-specific behavior
- **Database Abstraction:** PlatformServiceMixin handles database differences transparently
- **API Consistency:** Same TypeScript API across all platforms
- **Fallback Behavior:** Web platform gracefully degrades to push-only notifications

---
## 24) TimeSafari Architecture Compliance

### Design Pattern Adherence
- **Factory Pattern:** Notification service follows `PlatformServiceFactory` singleton pattern
- **Mixin Pattern:** Database access uses existing `PlatformServiceMixin` pattern
- **Migration Pattern:** Database changes follow existing `MIGRATIONS` array pattern
- **Error Handling:** Uses existing `handleApiError` from `src/services/api.ts`
- **Logging:** Uses existing logger from `src/utils/logger` with established patterns
- **Platform Detection:** Uses existing `Capacitor.isNativePlatform()` and `VITE_PLATFORM` patterns

### File Organization Compliance
- **Services:** Follows existing `src/services/` organization with factory and adapters
- **Database:** Extends existing `src/db-sql/migration.ts` and `src/db/tables/settings.ts`
- **Utils:** Extends existing `src/utils/PlatformServiceMixin.ts`
- **Main Entry:** Integrates with existing `src/main.capacitor.ts` initialization
- **Service Workers:** Follows existing `sw_scripts/` organization

### Type Safety Compliance
- **Settings Extension:** Follows existing Settings type extension pattern
- **Interface Definitions:** Uses existing TypeScript interface patterns
- **Error Types:** Follows existing error handling type patterns
- **Platform Types:** Uses existing platform detection type patterns

---

## Sync Checklist

| Sync item                      | Plan                  | Impl                  | Status    |
| ------------------------------ | --------------------- | --------------------- | --------- |
| Public API block identical     | §4                    | §3                    | ✅         |
| `getState()` fields present    | §4                    | §8 Orchestrator       | ✅         |
| Capacitor action handlers      | §7 (iOS/Android note) | §9 Bootstrap          | ✅         |
| Electron fetch prereq/polyfill | §7                    | §9 Electron           | ✅         |
| Android ±10m fallback          | §7                    | §7 SchedulerCapacitor | ✅         |
| Retention (no VACUUM v1)       | §5                    | `$pruneNotifData`     | ✅         |

---

*This strategic plan focuses on features and future‑tense deliverables, avoids implementation details, and preserves a clear path from the in‑app implementation (v1) to the native plugin (v2). For detailed implementation specifics, see `notification-system-implementation.md`.*