# 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).
