# Push Notifications

> **Status:** Active
> **Last updated:** 2026-07-05

## Overview

Mobile remote push (FCM/APNs) and server-side device token storage. Desktop uses local/Electron notifications via the `notifications` domain.

## Responsibilities

| Layer | Owns |
|-------|------|
| Signaling server | `device_tokens` SQLite table; FCM/APNs dispatch |
| Capacitor client | Token registration via `MobilePushRegistrationService` |
| Server env | FCM service account + APNs key configuration |

## REST API (`/api/users/device-tokens`)

All routes require bearer; `userId` must match authenticated identity.

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/` | Upsert `{ userId, platform: "android"\|"ios", token }` |
| GET | `/:userId` | List tokens for user |
| POST | `/:userId/dispatch` | Manual push `{ title, body, data? }` (ops/testing) |

## Server configuration

Repository-root `.env`:

| Variable | Purpose |
|----------|---------|
| `FCM_SERVICE_ACCOUNT_PATH` or `FCM_SERVICE_ACCOUNT_JSON` | Android FCM HTTP v1 |
| `APNS_KEY_PATH`, `APNS_KEY_ID`, `APNS_TEAM_ID` | iOS APNs HTTP/2 |
| `APNS_BUNDLE_ID` | Default `com.metoyou.app` |
| `APNS_USE_SANDBOX` | Development builds |

## Mobile client

- Optional Firebase: app starts without `google-services.json`; registration skipped when remote push not configured.
- See [mobile-capacitor.md](mobile-capacitor.md) for FCM/APNs setup, permissions, and in-call local notifications.

## Related

- [authentication.md](authentication.md) — bearer + userId match rules
- [mobile-capacitor.md](mobile-capacitor.md) — client registration and foreground service

## Changelog

| Date | Change |
|------|--------|
| 2026-07-05 | Initial push notification contract |