Toju/agents-docs/features/push-notifications.md

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 for FCM/APNs setup, permissions, and in-call local notifications.

Related

• authentication.md — bearer + userId match rules
• mobile-capacitor.md — client registration and foreground service

Changelog

Date	Change
2026-07-05	Initial push notification contract