Push Notifications Maintenance¶
Last audited: 2026-05-30.
Use this runbook when changing or investigating MamNajem mobile push notifications across mobile, backend, and infrastructure.
Despite the file name, AWS SNS is not the current end-to-end mobile push delivery path in the local code. Current source state:
- Mobile native bootstrap obtains Firebase Messaging registration tokens and
posts them to
POST /v1/push-tokens. - Backend
PushTokenServicestores raw token values and does not create SNS platform endpoints. - Backend
NotificationServicereads stored token values and passes them toPushSender. - The active backend sender is
ExpoPushSender, which posts stored token values to the Expo Push API. - Terraform and backend config still contain Android SNS platform application/runtime pieces, but current backend publishing does not use SNS endpoint ARNs.
Do not assume SNS endpoint ARN storage or publishing is live unless the backend code has changed.
Current Source Files¶
Re-read these files before accepting push-notification changes:
mobile-frontend/hooks/notifications/usePushNotificationsBootstrap.native.tsmobile-frontend/utils/notifications/backend/src/main/java/pl/mamnajem/service/PushTokenService.javabackend/src/main/java/pl/mamnajem/service/NotificationService.javabackend/src/main/java/pl/mamnajem/service/ExpoPushSender.javabackend/src/main/java/pl/mamnajem/controller/PushTokensController.javaarchitecture/terraform/aws-integration/main.tfarchitecture/terraform/aws-production/main.tf
Routine Review¶
- Confirm the mobile app registers the intended token format. Current native
code uses Firebase Messaging tokens, not Expo
getExpoPushTokenAsync(). - Confirm
POST /v1/push-tokensaccepts the current mobile token shape. - Confirm backend storage does not expose raw tokens in API responses or logs.
- Confirm backend sends through the intended
PushSender. Current code usesExpoPushSender. - Confirm
snsEndpointArnis not treated as required unless backend code creates SNS platform endpoints. - Confirm Android and iOS runtime credentials match the chosen delivery path.
- Confirm integration uses Firebase project
mamnajem-int. - Confirm production changes are source-only until the user explicitly performs a manual production rollout.
Suggested Verification¶
Backend:
mvn -q -Dtest=NotificationServiceTest,PushTokenServiceTest test
Architecture:
terraform fmt -recursive -check
./scripts/tf.sh all-validate
Mobile:
pnpm exec jest hooks/notifications/usePushNotificationsBootstrap.native.test.ts utils/notifications/push-token-storage.test.ts --runInBand
pnpm check
If a full command is too expensive or blocked by local credentials, run the most relevant targeted command and record the blocker in the change notes.
Manual Review Checklist¶
Before pushing any result:
- Confirm no real secrets were added.
- Confirm no raw device tokens, Expo tokens, APNs keys, FCM service account JSON, endpoint ARNs tied to users, or user IDs were added to logs or docs.
- Confirm backend stores the intended token value and does not expose raw tokens in API responses or logs.
- Confirm backend sends through the intended delivery path.
- Confirm Android and iOS runtime credentials match the selected delivery path.
- Confirm integration and production environment variables are documented when configuration changes.
Runtime Smoke After Human-Approved Deploy¶
Use physical Android and iOS devices, not Expo Go or simulators.
For integration:
- Install the latest integration build.
- Sign in and enable push notifications.
- Confirm
POST /v1/push-tokensreturns201. - Confirm the response has no raw token or
snsEndpointArn. - Confirm the backend stores the token row for the user.
- Trigger a message or payment notification.
- Confirm push delivery on both platforms.
- Check backend logs for Expo push request failures, ticket failures, unregistered-token cleanup, or token-format rejection.
Repeat after a user-controlled production rollout.