cinny/docs/handoff/features/background-notifications/HANDOFF.md

Background notifications — handoff

Summary

Paarrot keeps users notified of Matrix activity when the app is in the background: desktop tray/favicon badges, system notifications (Electron/Tauri/Android), and Android UnifiedPush for reliable mobile push without Google FCM dependency.

User-facing behavior

• Unread counts update favicon (Paarrot / unread / highlight variants)
• System notifications for mentions/DMs per notification settings
• Android: requires UnifiedPush distributor (e.g. ntfy); user prompted if missing
• Foreground/background state affects sync strategy

Architecture

ClientNonUIFeatures.tsx
  → FaviconUpdater (roomToUnread atom)
  → notification listeners (tauri.ts sendNotification)
  → initPaarrotAPI + background sync lifecycle
backgroundSync.ts
  → UnifiedPush registration, pusher setup
  → setAppForegroundState / startBackgroundSync / stopBackgroundSync
tauri.ts / electron main
  → OS notification APIs, Android small icon ic_stat_paarrot

Key files

Path	Role
cinny/src/app/pages/client/ClientNonUIFeatures.tsx	Favicon, notifications, API init, background sync hooks
cinny/src/app/utils/backgroundSync.ts	Pushers, UnifiedPush, foreground state
cinny/src/app/utils/tauri.ts	Tauri/Capacitor notification helpers
cinny/src/app/features/settings/notifications/SystemNotification.tsx	Permission UX
electron/main.js	Tray, notification IPC (if applicable)
src-tauri/src/main.rs	Tauri Android shell

Data model

Key	Storage	Purpose
paarrot.unifiedpush.*	localStorage prefix	UP endpoint state
com.paarrot.app.android	Pusher app id base	Android pushers
Matrix pusher	Homeserver	HTTP push gateway

Dependencies

• UnifiedPush distributor app on Android
• Notification permission (browser/OS)
• Homeserver pusher support
• matrix-js-sdk sync

Integration points

• Settings → Notifications: rules + system permission
• DirectTab / sidebar: custom Paarrot SVG favicon states
• Deep links: notification tap → setupNotificationTapListener

Testing

Manual

1. Desktop: background app; send mention; verify system notification.
2. Verify favicon switches unread/highlight with counts.
3. Android: install ntfy; verify push when app killed.
4. Toggle notification settings; verify respect mute rules.

Automated

• None

Known issues & gotchas

• UnifiedPush user education string in backgroundSync.ts if no distributor
• Multiple runtimes: isTauri, isElectron, isCapacitorNative branch logic
• Pusher registration races on fast login/logout
• Android small icon: ic_stat_paarrot must exist in Android resources
• Background wake (MatrixSyncService) must filter by push rules / unread_notifications; a push for one room used to notify for every new message in the sync batch

Future work

• iOS push strategy
• Notification action buttons (reply, mark read)
• Per-room notification channels on Android

Related docs

• Matrix push gateway docs (upstream)

Add your extra things here

• Constants: PUSHER_APP_ID_BASE, PUSHER_STORAGE_PREFIX in backgroundSync.ts
• Logo assets: paarrot.svg, paarrot-unread.svg, paarrot-highlight.svg in public/res/svg/
• Android notify filter: mute / mentions / default-room behavior lives in MatrixSyncService.resolveRoomNotifyMode