gemstone-nexus · Phase 6
DOC — GemStone Push Notifications (AWS SNS + FCM + Capacitor)
Metadata
| id | doc_id | title | category | source_path | summary | content_hash | indexed_at |
|---|---|---|---|---|---|---|---|
| 49 | DOC-PUSH-NOTIFICATIONS-SNS | DOC — GemStone Push Notifications (AWS SNS + FCM + Capacitor) | reference | DevResources/docs/DOC-Push-Notifications-SNS.md | Do these in order. Do **not** paste secret values into chat or git. | 77f96dbb30a4fac7af18b6afdc34ef5d21808fc2 | 2026-07-23 15:20:09 |
Content
# DOC — GemStone Push Notifications (AWS SNS + FCM + Capacitor)
**Status:** Scaffold live 2026-07-23 · Real device push **blocked** until Mark creates Firebase + secrets
**Stack:** AWS SNS Mobile Push → FCM (Android) · Capacitor `@capacitor/push-notifications` · **not MQTT**
**Policy:** Messaging is AWS-native only (DOC06). No Twilio.
**App ID (verified):** Capacitor / Android package = **`com.nextech.gemstone`**
**In-app guide link (already live):** `/install-android` → “Enable notifications” → links this doc on GitHub. Admin settings also points here.
---
## Follow the bouncing ball (Mark / ops)
Do these in order. Do **not** paste secret values into chat or git.
### 1. Firebase — Android app
1. Open [Firebase Console](https://console.firebase.google.com/).
2. Create a project (e.g. `gemstone-dataright`) or select an existing one.
3. **Add app** → **Android**.
4. Package name: **`com.nextech.gemstone`** (must match Capacitor `appId` / `applicationId` — verified in repo).
5. Register the app (nickname optional; SHA-1 optional for push-only).
### 2. Place `google-services.json`
1. Download **`google-services.json`** from the Firebase Android app settings.
2. Place it at:
```
frontend/android/app/google-services.json
```
3. Do **not** commit it if it contains project keys you treat as sensitive (prefer secure channel / local only for APK rebuild). Capacitor Push Notifications uses this file at build time; no extra Firebase SDK wiring is required in app code.
### 3. Get FCM credentials for SNS
1. Firebase → Project settings → **Cloud Messaging**.
2. Prefer **Cloud Messaging API (V1)** enabled.
3. For AWS SNS Platform Application (`GCM`), you still need a **Server key** (legacy Cloud Messaging API) **or** follow AWS’s current FCM credential guidance for the platform credential.
4. Copy the server key once locally — **never** paste into chat/git.
### 4. Secrets → `DATARIGHT_DEV_SECRETS` (us-east-1)
Update AWS Secrets Manager secret **`DATARIGHT_DEV_SECRETS`** (region **us-east-1**) with these **exact** JSON key names (string values):
| Key | When | Purpose |
| --- | --- | --- |
| `FCM_SERVER_KEY` | Now (after step 3) | FCM legacy server key → SNS `PlatformCredential` for Android (GCM) |
| `FCM_PROJECT_ID` | Now (optional but recommended) | Firebase project id (ops / docs; not required for SNS publish path) |
| `SNS_PUSH_PLATFORM_ARN_ANDROID` | **After** step 5 | SNS platform application ARN |
| `AWS_SNS_REGION` | Already present for SMS/SES | Prefer `us-east-1` |
| `SES_FROM_EMAIL` | Already used | Email fallback when push not configured |
API reads the same names from env (compose / host). Confirmed in `api/app/core/config.py`:
```
SNS_PUSH_PLATFORM_ARN_ANDROID
SNS_PUSH_PLATFORM_ARN_IOS
FCM_SERVER_KEY
FCM_PROJECT_ID
AWS_SNS_REGION
SES_FROM_EMAIL
```
When keys are in Secrets Manager (no values in chat), reply to the agent:
> **FCM credentials are in DATARIGHT_DEV_SECRETS**
### 5. SNS platform application (Android / FCM)
**Only after** `FCM_SERVER_KEY` is in secrets/env. Do not create with empty credentials.
```bash
# Region: us-east-1 (match AWS_SNS_REGION)
aws sns create-platform-application \
--name GemStone-Android-FCM \
--platform GCM \
--attributes PlatformCredential="<FCM_SERVER_KEY>" \
--region us-east-1
```
1. Response includes `PlatformApplicationArn`.
2. Store it as `SNS_PUSH_PLATFORM_ARN_ANDROID` in `DATARIGHT_DEV_SECRETS`.
3. Recreate / restart `gemstone-api` so config picks up the new env/secrets.
4. Verify (no secrets printed):
```bash
aws sns list-platform-applications --region us-east-1 \
--query "PlatformApplications[?contains(PlatformApplicationArn, 'GemStone')]"
```
Endpoint creation is automatic at register time (`CreatePlatformEndpoint` + store `sns_endpoint_arn`).
### 6. Rebuild / reinstall the Android APK
Rebuild is required after adding `google-services.json` (FCM cannot issue device tokens without it).
1. From `frontend/`: sync + assemble per [CAPACITOR-ANDROID-INSTALLATION-PLAYBOOK.md](./CAPACITOR-ANDROID-INSTALLATION-PLAYBOOK.md) (e.g. `npm run cap:sync:android`, then Android Studio Run **or** Gradle assemble).
2. Install on a physical Android device (emulators often lack reliable FCM).
3. Or use the live install path: **https://gemstone.dataright.net/install-android** after a new APK is published there.
### 7. Sign in → enable → register token → verify test push
1. Open the installed GemStone app (`com.nextech.gemstone`).
2. **Sign in** with your local GemStone account (email/password JWT).
3. Allow **notification permission** when prompted. On login, the app calls Capacitor `PushNotifications.register()` and `POST /api/push/register` with the FCM token.
4. Confirm server-side config (signed-in):
```http
GET /api/push/status
```
Expect `sns_android_configured: true` once `SNS_PUSH_PLATFORM_ARN_ANDROID` is loaded by the API.
5. Confirm a row exists for your practitioner in `device_push_tokens` (platform `android`, token present; `sns_endpoint_arn` set when SNS ARN is configured).
6. **Trigger a test push** (no dedicated `/api/push/test` route — use real hooks):
- Cause a Didymus event that needs approval, **or** complete/fail a Didymus task — both call `notify_practitioner` / org approval notify (best-effort; never breaks the approval gate).
- Or from ops: SNS Console → publish to the device’s `sns_endpoint_arn` with a GCM JSON payload.
7. Device should show the notification. If SNS/FCM is not ready, API falls back to **SES email** when `SES_FROM_EMAIL` and practitioner email are known; otherwise it skips quietly.
### 8. What’s already live vs blocked
| Capability | Status |
| --- | --- |
| Alembic `device_push_tokens` + `/api/push/register` · `/unregister` · `/status` | **Live (scaffold)** |
| `notify_practitioner` (SNS or SES or skip) | **Live (scaffold)** |
| Didymus hooks (approval needed / task completed) | **Live** — best-effort; gate untouched |
| Capacitor plugin + register-on-login | **Live (scaffold)** — tokens work once FCM issues them |
| `/install-android` + Admin copy linking this doc | **Live** |
| Real Android push delivery | **Blocked** — needs Firebase + `FCM_SERVER_KEY` + SNS platform app + `SNS_PUSH_PLATFORM_ARN_ANDROID` + APK with `google-services.json` |
| iOS / APNs | **Deferred** (see below) |
Rolling deploys: API + migration are additive; missing FCM/SNS env leaves push as no-op + SES fallback. Live site stays up.
### 9. iOS / APNs (deferred — do not block Android)
1. Apple Developer: App ID + Push Notifications for the iOS bundle id (`com.nextech.gemstone`).
2. Create APNs key or certificate; upload to SNS (`APNS` or `APNS_SANDBOX`).
3. Store `SNS_PUSH_PLATFORM_ARN_IOS` (and optional `APNS_PLATFORM_CREDENTIAL` material) in secrets.
4. Capacitor iOS registration already scaffolds via the same plugin; enable when the APNs ARN exists.
---
## Architecture
```
Android / iOS (Capacitor)
│ FCM / APNs device token
▼
POST /api/push/register → device_push_tokens (+ optional SNS endpoint ARN)
│
Didymus / other events
│
notify_practitioner(practitioner_id, title, body, data)
├─ if SNS_PUSH_PLATFORM_ARN_* set → SNS Publish to endpoint ARN(s)
└─ else → SES email to practitioner email (if known) / skip gracefully
```
| Layer | Role |
| --- | --- |
| Capacitor Push Notifications | Requests permission, obtains FCM token on Android, registers with API on login |
| `device_push_tokens` | Per-practitioner token store (`platform`, `token`, `sns_endpoint_arn`, `updated_at`) |
| AWS SNS Platform Application | Maps FCM credentials → platform ARN; CreatePlatformEndpoint per device token |
| FCM | Google delivery to Android devices |
| APNs | Deferred — iOS later (same SNS pattern, `SNS_PUSH_PLATFORM_ARN_IOS`) |
| SES fallback | When SNS/FCM not configured: email via `SES_FROM_EMAIL` if practitioner email known |
## Deploy safety
- Additive migration + optional env; no hard dependency on FCM at boot.
- Didymus approve / lease / schema gate unchanged — notify is try/except best-effort.
- Alembic: `0012_device_push_tokens` revises `0011_practitioner_rules`.
## Related
- Punchlist: `DOC07-Punchlist.md` (Firebase checklist)
- Capacitor install: `CAPACITOR-ANDROID-INSTALLATION-PLAYBOOK.md`
- Messaging policy: `DOC06-Master-Prompt.md`
- Live UI: `/install-android` (Enable notifications), Admin → notifications note