Skip to content

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 PushTokenService stores raw token values and does not create SNS platform endpoints.
  • Backend NotificationService reads stored token values and passes them to PushSender.
  • 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.ts
  • mobile-frontend/utils/notifications/
  • backend/src/main/java/pl/mamnajem/service/PushTokenService.java
  • backend/src/main/java/pl/mamnajem/service/NotificationService.java
  • backend/src/main/java/pl/mamnajem/service/ExpoPushSender.java
  • backend/src/main/java/pl/mamnajem/controller/PushTokensController.java
  • architecture/terraform/aws-integration/main.tf
  • architecture/terraform/aws-production/main.tf

Routine Review

  1. Confirm the mobile app registers the intended token format. Current native code uses Firebase Messaging tokens, not Expo getExpoPushTokenAsync().
  2. Confirm POST /v1/push-tokens accepts the current mobile token shape.
  3. Confirm backend storage does not expose raw tokens in API responses or logs.
  4. Confirm backend sends through the intended PushSender. Current code uses ExpoPushSender.
  5. Confirm snsEndpointArn is not treated as required unless backend code creates SNS platform endpoints.
  6. Confirm Android and iOS runtime credentials match the chosen delivery path.
  7. Confirm integration uses Firebase project mamnajem-int.
  8. 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:

  1. Install the latest integration build.
  2. Sign in and enable push notifications.
  3. Confirm POST /v1/push-tokens returns 201.
  4. Confirm the response has no raw token or snsEndpointArn.
  5. Confirm the backend stores the token row for the user.
  6. Trigger a message or payment notification.
  7. Confirm push delivery on both platforms.
  8. Check backend logs for Expo push request failures, ticket failures, unregistered-token cleanup, or token-format rejection.

Repeat after a user-controlled production rollout.