crowd-funder-for-time-pwa/doc/daily-notification-plugin-architecture.md

Daily Notification Plugin - Architecture Overview

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Vue Components                            │
│  (PushNotificationPermission.vue, AccountViewView.vue, etc.)    │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│              NotificationService (Factory)                       │
│           - Platform detection via Capacitor API                 │
│           - Singleton pattern                                    │
│           - Returns appropriate implementation                   │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                ┌───────────┴────────────┐
                ▼                        ▼
┌───────────────────────────┐  ┌────────────────────────────┐
│ NativeNotificationService │  │ WebPushNotificationService │
│                           │  │                            │
│ iOS/Android               │  │ Web/PWA                    │
│ - UNUserNotificationCenter│  │ - Web Push API             │
│ - NotificationManager     │  │ - Service Workers          │
│ - AlarmManager            │  │ - VAPID keys               │
│ - Background tasks        │  │ - Push server              │
└─────────────┬─────────────┘  └────────────┬───────────────┘
              │                              │
              ▼                              ▼
┌─────────────────────────┐  ┌──────────────────────────────┐
│  DailyNotificationPlugin│  │  Existing Web Push Logic     │
│  (Capacitor Plugin)     │  │  (PushNotificationPermission)│
│                         │  │                              │
│  - Native iOS code      │  │  - Service worker            │
│  - Native Android code  │  │  - VAPID subscription        │
│  - SQLite storage       │  │  - Push server integration   │
└─────────────────────────┘  └──────────────────────────────┘

Platform Decision Flow

User Action: Schedule Notification
         │
         ▼
   NotificationService.getInstance()
         │
         ├──> Check: Capacitor.isNativePlatform()
         │
    ┌────┴─────┐
    │          │
   YES        NO
    │          │
    ▼          ▼
Native      Web/PWA
Service     Service
    │          │
    ▼          ▼
Plugin      Web Push

Data Flow Example: Scheduling a Notification

Native Platform (iOS/Android)

1. User clicks "Enable Notifications"
   │
2. PushNotificationPermission.vue
   │
   └─> NotificationService.getInstance()
       │
       └─> Returns NativeNotificationService (detected iOS/Android)
           │
           └─> nativeService.requestPermissions()
               │
               └─> DailyNotification.requestPermissions() [Capacitor Plugin]
                   │
                   └─> Native code requests OS permissions
                       │
                       └─> Returns: { granted: true/false }

3. User sets time & message
   │
4. nativeService.scheduleDailyNotification({ time: '09:00', ... })
   │
   └─> DailyNotification.scheduleDailyReminder({ ... })
       │
       └─> Native code:
           - Stores in SQLite
           - Schedules AlarmManager (Android) or UNNotificationRequest (iOS)
           - Returns: success/failure

5. At 9:00 AM:
   - Android: AlarmManager triggers → DailyNotificationReceiver
   - iOS: UNUserNotificationCenter triggers notification
   - Notification appears even if app is closed

Web Platform

1. User clicks "Enable Notifications"
   │
2. PushNotificationPermission.vue
   │
   └─> NotificationService.getInstance()
       │
       └─> Returns WebPushNotificationService (detected web)
           │
           └─> webService.requestPermissions()
               │
               └─> Notification.requestPermission() [Browser API]
                   │
                   └─> Returns: 'granted'/'denied'/'default'

3. User sets time & message
   │
4. webService.scheduleDailyNotification({ ... })
   │
   └─> [TODO] Subscribe to push service with VAPID
       │
       └─> Send subscription to server with schedule time
           │
           └─> Server sends push at scheduled time
               │
               └─> Service worker receives → shows notification

File Organization

src/
├── plugins/
│   └── DailyNotificationPlugin.ts          [Plugin registration]
│
├── services/
│   └── notifications/
│       ├── index.ts                        [Barrel export]
│       ├── NotificationService.ts          [Factory + Interface]
│       ├── NativeNotificationService.ts    [iOS/Android impl]
│       └── WebPushNotificationService.ts   [Web impl stub]
│
├── components/
│   └── PushNotificationPermission.vue      [UI - to be updated]
│
└── views/
    └── AccountViewView.vue                 [Settings UI]

Key Design Decisions

1. Unified Interface

• Single NotificationServiceInterface for all platforms
• Consistent API regardless of underlying implementation
• Type-safe across TypeScript codebase

2. Runtime Platform Detection

• No build-time configuration needed
• Same code bundle for all platforms
• Factory pattern selects implementation automatically

3. Coexistence Strategy

• Web Push and Native run on different platforms
• No conflicts - mutually exclusive at runtime
• Allows gradual migration and testing

4. Singleton Pattern

• One service instance per app lifecycle
• Efficient resource usage
• Consistent state management

Permission Flow

Android

App Launch
  ↓
Check if POST_NOTIFICATIONS granted (API 33+)
  │
  ├─> YES: Ready to schedule
  │
  └─> NO: Request runtime permission
          ↓
      Show system dialog
          ↓
      User grants/denies
          ↓
      Schedule notifications (if granted)

iOS

App Launch
  ↓
Check notification authorization status
  │
  ├─> authorized: Ready to schedule
  │
  ├─> notDetermined: Request permission
  │       ↓
  │   Show system dialog
  │       ↓
  │   User grants/denies
  │
  └─> denied: Guide user to Settings

Web

App Load
  ↓
Check Notification.permission
  │
  ├─> "granted": Ready to subscribe
  │
  ├─> "default": Request permission
  │       ↓
  │   Show browser prompt
  │       ↓
  │   User grants/denies
  │
  └─> "denied": Cannot show notifications

Error Handling Strategy

// All methods return promises with success/failure
try {
  const granted = await service.requestPermissions();
  if (granted) {
    const success = await service.scheduleDailyNotification({...});
    if (success) {
      // Show success message
    } else {
      // Show scheduling error
    }
  } else {
    // Show permission denied message
  }
} catch (error) {
  // Log error and show generic error message
  logger.error('Notification error:', error);
}

Background Execution

Native (iOS/Android)

• ✅ Full background support
• ✅ Survives app termination
• ✅ Survives device reboot (with BootReceiver)
• ✅ Exact alarm scheduling
• ✅ Works offline

Web/PWA

• ⚠️ Limited background support
• ⚠️ Requires active service worker
• ⚠️ Browser/OS dependent
• ❌ Needs network for delivery
• ⚠️ iOS: Only on Home Screen PWAs (16.4+)

Storage

Native

DailyNotificationPlugin
    ↓
SQLite Database (Room/Core Data)
    ↓
Stores:
- Schedule configurations
- Content cache
- Delivery history
- Callback registrations

Web

Web Push
    ↓
IndexedDB (via Dexie)
    ↓
Stores:
- Settings (notifyingNewActivityTime, etc.)
- Push subscription info
- VAPID keys

Testing Strategy

Unit Testing

• Mock Capacitor.isNativePlatform() to test both paths
• Test factory returns correct implementation
• Test each service implementation independently

Integration Testing

• Test on actual devices (iOS/Android)
• Test in browsers (Chrome, Safari, Firefox)
• Verify notification delivery
• Test permission flows

E2E Testing

• Schedule notification → Wait → Verify delivery
• Test app restart scenarios
• Test device reboot scenarios
• Test permission denial recovery

---

Key Takeaway: The architecture provides a clean separation between platforms while maintaining a unified API for Vue components. Platform detection happens automatically at runtime, and the appropriate notification system is used transparently.