E15-F2: Push Notification Service¶

Epic: E15: Notifications & Communications

Size: M (Medium)

Problem / Outcome¶

Send push notifications to mobile app.

Scope¶

In-Scope:

Firebase FCM integration
Priority levels (normal, high)
High capacity for queue scenarios (100k+ concurrent)

Out-of-Scope:

SMS

Acceptance Criteria¶

AC1: Push notification delivered to user's device
AC2: High priority for "your turn" notifications
AC3: Handles 100k+ concurrent notifications

Data Model Impact¶

PushToken table:
- id (UUID, PK)
- user_id (UUID, FK)
- device_id (VARCHAR)
- fcm_token (VARCHAR)
- platform (ENUM: ios, android)
- is_active (BOOLEAN)
- created_at (TIMESTAMP)
- last_used_at (TIMESTAMP)

PushLog table:
- id (UUID, PK)
- user_id (UUID, FK)
- notification_type (VARCHAR)
- title (VARCHAR)
- body (TEXT)
- data_json (JSONB)
- priority (ENUM: normal, high)
- fcm_message_id (VARCHAR)
- status (ENUM: queued, sent, delivered, failed)
- sent_at (TIMESTAMP)
- error_message (VARCHAR, nullable)

Notification types:
- queue_position_update
- queue_your_turn
- ticket_purchased
- ticket_transferred
- match_update
- match_cancellation
- loyalty_points_awarded
- quota_received

Permissions/Roles¶

System

How to Verify¶

npm test -- --grep "push notification"

Expected: Notifications delivered.

Dependencies¶

None (external service)

Implementation Tasks¶

See E15: Notifications Tasks

Doc References¶

Last Updated: January 2026