rosterchirp/KNOWN_LIMITATIONS.md

RosterChirp — Known Limitations

Android Background Push Notifications

Status: Known limitation — deferred
Affects: Android Chrome browser and Android PWA installs
Does not affect: Desktop browsers, iOS PWA (iOS 16.4+)

Symptom

Push notifications are not delivered when the RosterChirp PWA or Chrome browser loses focus on Android. The app also disconnects from the WebSocket (real-time chat) when backgrounded. Notifications only arrive while the app is open and in the foreground.

Root Cause

Android's battery optimization system (Doze mode + App Standby) aggressively kills background network connections for browsers. This affects two things:

1. WebSocket — the socket.io connection is dropped when Chrome/PWA loses focus, stopping real-time updates until the user returns to the app.
2. Web Push — RosterChirp uses the standard Web Push API with VAPID keys. Android throttles or blocks push delivery at the system level even when battery settings are set to "No restrictions", because that setting only controls the app's own background activity — it does not exempt the browser's push service socket.

Setting Chrome or the PWA to "No battery restrictions" in Android settings does not resolve this.

Why FCM Would Fix It

Firebase Cloud Messaging (FCM) maintains a privileged persistent connection that Android explicitly exempts from Doze mode. This is the only reliable mechanism for background push delivery on Android. All major Android messaging apps (WhatsApp, Telegram, Signal) use FCM or a vendor-equivalent for this reason.

Future Fix Plan

1. Create a Firebase project (free tier is sufficient)
2. Add Firebase config to .env and sw.js
3. Replace web-push subscription flow with Firebase SDK — VAPID keys are reusable so existing subscriptions can be migrated
4. Switch backend notification dispatch from web-push to firebase-admin
5. Address WebSocket reconnect-on-focus separately (frontend only, no Firebase needed)

Workaround for Users

None at the app level. Users who need reliable Android notifications should keep the RosterChirp PWA pinned/open, or check their Android vendor's specific battery exemption settings (Samsung DeX, MIUI, etc. have additional per-app exemption controls beyond the standard Android settings).