Push Notifications
Relevant source files
The following files were used as context for generating this wiki page:
The Push Notifications system in the Happy ecosystem facilitates real-time alerts and user engagement by delivering asynchronous updates from the server to mobile clients. This system is critical for notifying users about session state changes, new messages in active coding sessions, and pairing requests between the CLI and mobile devices.
The architecture spans multiple platforms, including native iOS (APNs), Android (FCM), and backend implementations in both the Fastify API server and Cloudflare Workers. By leveraging platform-specific notification services, the system ensures that users remain informed even when the application is in the background or the device is locked.
Sources: apps/mobile/ios/CLAUDE.md:215-225, apps/mobile/android/CLAUDE.md:210-215
System Architecture
The push notification system follows a provider-subscriber model where mobile clients register unique device tokens with the Happy server, which then uses these tokens to relay messages through Apple Push Notification service (APNs) or Firebase Cloud Messaging (FCM).
High-Level Data Flow
The following diagram illustrates the flow from a server-side event to a mobile notification:
The server identifies the need for a notification, retrieves stored tokens for the associated user, and dispatches the payload to the appropriate platform gateway.
Sources: apps/server/docker/sources/apps/api/routes/pushNotifications.ts, apps/server/workers/src/routes/push.ts
Mobile Implementation
iOS (APNs)
On iOS, the PushNotificationService acts as a singleton manager for registration and handling. It coordinates with the AppDelegate to receive device tokens from Apple and stores them securely in the Keychain.
| Feature | Description |
|---|---|
| Registration | Requests user permission and registers for remote notifications. |
| Token Storage | Stores the deviceToken in Keychain via KeychainHelper.Key.deviceToken. |
| Categories | Supports SESSION_UPDATE, MESSAGE, and PAIRING categories. |
| Actions | Enables inline replies for messages and approve/reject for pairing requests. |
Sources: apps/mobile/ios/Happy/Services/PushNotificationService.swift:10-40, apps/mobile/ios/CLAUDE.md:227-235
Android (FCM)
The Android implementation utilizes Firebase Cloud Messaging. It includes an FCM service for token management and channel configuration to support rich notifications and custom actions.
Sources: apps/mobile/android/CLAUDE.md:210-215
Server-Side API
The backend provides endpoints for mobile clients to manage their push tokens. Both the Docker-based Fastify server and the Cloudflare Workers edge functions implement these routes.
Token Management Endpoints
| Endpoint | Method | Description |
|---|---|---|
/v1/push-tokens | POST | Register or update a device push token for the authenticated user. |
/v1/push-tokens | GET | Retrieve all registered tokens for the current user. |
/v1/push-tokens/:id | DELETE | Remove a specific device token (e.g., on logout). |
Sources: apps/server/docker/sources/apps/api/routes/pushNotifications.ts:15-45, apps/server/workers/src/routes/push.ts:10-30
Notification Categories
The system categorizes notifications to provide distinct UI experiences on the mobile device:
- SESSION_UPDATE: Triggered when a session completes, encounters an error, or requires user input.
- MESSAGE: Sent for new messages in a coding session, supporting quick replies.
- PAIRING: Alerts the user to a connection request from a CLI instance, providing approve/reject buttons.
Sources: apps/mobile/ios/CLAUDE.md:220-225
Registration Sequence
The registration process involves a handshake between the mobile hardware, the platform provider, and the Happy API server.
This sequence ensures that the server always has the most current routing information for a user's active devices.
Sources: apps/mobile/ios/Happy/Services/PushNotificationService.swift:45-60, apps/server/docker/sources/apps/api/routes/pushNotifications.ts:20-35
Conclusion
The Push Notification system provides a seamless bridge between the CLI-driven coding sessions and the mobile management interface. By integrating native iOS and Android services with a unified backend token management API, Happy ensures that critical updates—such as agent requests for permission or tool execution status—reach the user instantly, regardless of device state. This asynchronous communication is vital for the "remote control" utility of the application.
Sources: apps/mobile/ios/CLAUDE.md:210-215, apps/mobile/android/CLAUDE.md:210-215