# Specification: 005-firebase-push-notifications

## Status

| Field | Value |
|-------|-------|
| **Created** | 2025-12-30 |
| **Current Phase** | Phase 4 Complete - Ready for Phase 5 |
| **Last Updated** | 2025-12-30 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | All 4 notification types defined |
| solution-design.md | completed | Full architecture with Firebase setup guide |
| implementation-plan.md | completed | 7 phases, TDD approach, ~80 tasks |

**Status values**: `pending` | `in_progress` | `completed` | `skipped`

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2025-12-30 | FCM for push only, keep Ably | Use Firebase for background notifications, Ably remains for in-app real-time |
| 2025-12-30 | All 4 notification types | Schedule, Clock, Open Shifts, Team Chat all included |
| 2025-12-30 | Rich notifications with actions | Enable action buttons (Claim Shift, Clock In, Reply) |
| 2025-12-30 | In-app preference controls | Users can toggle notification categories in settings |
| 2025-12-30 | Use firebase_messaging package | Official FlutterFire package for FCM integration |
| 2025-12-30 | Foreground as in-app banner | Show custom banner when app is open, not system notification |
| 2025-12-30 | Implementation plan created | 7 phases with TDD approach, parallel work in Phases 5-6 |
| 2025-12-30 | Phase 1 completed | Firebase SDK integrated, apps registered, both platforms build |
| 2025-12-30 | APNs keys uploaded | Production and dev APNs keys added to Firebase Console |
| 2025-12-30 | Phase 2 completed | Core service, models, constants, storage extensions implemented |
| 2025-12-30 | Background handler registered | Added FirebaseMessaging.onBackgroundMessage() to main.dart |
| 2025-12-30 | Payload parsing improved | fromFcmData handles JSON string payloads, rejects empty types |
| 2025-12-30 | Duplicate listener prevention | Added _handlersInitialized flag to prevent duplicate handlers |
| 2025-12-30 | Phase 3 completed | NotificationState sealed class and NotificationNotifier provider implemented with 46 tests |
| 2025-12-30 | Phase 3 fixes | Added NotificationPayload domain entity, setupHandlersAfterPermissionGrant(), banner suppression when denied, NotificationConstants usage |
| 2025-12-30 | Phase 4 completed | Auth integration: FCM token registered on login, removed on logout, token refresh handling, notification initialization on app start |
| 2025-12-30 | API repository pattern | Refactored AuthRepositoryImpl to take ApiClient directly for consistency and testability |
| 2025-12-30 | package_info_plus added | Added to get app version for device registration payload |

## Context

User has created a fresh Firebase project for the BuyerKiosk Team app. The goal is to:
1. Set up Firebase project configuration
2. Integrate Firebase Cloud Messaging (FCM) into the Flutter app
3. Enable specific push notifications for various app functions (shifts, schedule changes, clock reminders, team chat, etc.)

The app already has:
- iOS Live Activity support for active shifts
- Ably configured for real-time messaging (may need to evaluate FCM vs Ably for notifications)
- Authentication flow with biometric support
- Schedule, clock, and open shifts features

---
*This file is managed by the specification-management skill.*