# Product Requirements Document

## Validation Checklist

- [x] All required sections are complete
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Problem statement is specific and measurable
- [x] Problem is validated by evidence (not assumptions)
- [x] Context → Problem → Solution flow makes sense
- [x] Every persona has at least one user journey
- [x] All MoSCoW categories addressed (Must/Should/Could/Won't)
- [x] Every feature has testable acceptance criteria
- [x] Every metric has corresponding tracking events
- [x] No feature redundancy (check for duplicates)
- [x] No contradictions between sections
- [x] No technical implementation details included
- [x] A new team member could understand this PRD

---

## Product Overview

### Vision
Keep team members informed and engaged with timely, actionable push notifications that reduce missed shifts, improve clock compliance, and enable faster response to schedule changes—all without requiring the app to be open.

### Problem Statement
Currently, team members must actively open the BuyerKiosk Team app to see schedule changes, open shifts, clock reminders, or team messages. This leads to:
- **Missed shifts**: Team members don't see last-minute schedule changes until it's too late
- **Clock compliance issues**: Employees forget to clock in/out, leading to timesheet corrections
- **Slow shift coverage**: Open shifts go unclaimed because team members don't know they're available
- **Delayed communication**: Important team messages aren't seen promptly

Without proactive notifications, managers must resort to calling/texting employees directly, creating inefficiency and inconsistent communication.

### Value Proposition
Firebase Push Notifications transform the BuyerKiosk Team app from a "check when you remember" tool into a proactive assistant that:
- **Never lets you miss a shift**: Get notified of schedule changes and upcoming shifts
- **Keeps you on time**: Clock reminders ensure you never forget to punch in/out
- **Helps you earn more**: Be first to know about open shifts you can claim
- **Keeps you connected**: Stay in the loop with team communication even when the app is closed
- **Puts you in control**: Customize exactly which notifications you receive

---

## User Personas

### Primary Persona: Team Member (Hourly Employee)
- **Demographics:** Ages 16-45, hourly retail/service workers, varying technical expertise (most comfortable with smartphone basics)
- **Goals:**
  - Know their schedule without constantly checking the app
  - Never miss a shift or be late
  - Pick up extra hours when available
  - Stay connected with their team
- **Pain Points:**
  - Forgets to check the app and misses schedule changes
  - Gets surprised by shift changes discovered too late
  - Misses open shift opportunities because others claim them first
  - Has to manually remember to clock in/out

### Secondary Persona: Store Manager
- **Demographics:** Ages 25-55, store leadership, moderate technical expertise
- **Goals:**
  - Ensure adequate shift coverage
  - Reduce timesheet corrections from missed punches
  - Communicate quickly with team members
  - Fill open shifts rapidly
- **Pain Points:**
  - Spends time calling employees about schedule changes
  - Deals with timesheet corrections from forgotten clock actions
  - Open shifts stay unfilled because employees don't see them
  - Important announcements don't reach everyone

---

## User Journey Maps

### Primary User Journey: Schedule Change Notification
1. **Trigger:** Manager publishes a schedule change affecting a team member
2. **Notification:** Team member receives push notification: "Schedule Updated: Your Tuesday shift changed to 2pm-8pm"
3. **Action:** Team member taps notification to view full schedule details
4. **Confirmation:** App opens directly to schedule screen showing the change
5. **Retention:** Team member trusts the app to keep them informed, reduces anxiety about missing changes

### Secondary User Journey: Open Shift Claim
1. **Trigger:** A shift becomes available that matches team member's qualifications
2. **Notification:** Team member receives push: "Open Shift Available: Wed 10am-4pm at Store #123"
3. **Action:** Team member taps "Claim Shift" button directly from notification
4. **Confirmation:** Shift claimed, confirmation notification sent
5. **Retention:** Team member earns extra hours, becomes active open shift watcher

### Tertiary User Journey: Clock-In Reminder
1. **Trigger:** Team member's shift starts in 15 minutes, hasn't clocked in yet
2. **Notification:** Push notification: "Shift starts soon! Clock in for your 2pm shift"
3. **Action:** Team member taps "Clock In" button from notification (if within geofence)
4. **Confirmation:** Clock-in recorded, Live Activity starts on lock screen
5. **Retention:** Team member builds habit of on-time clock-ins, fewer timesheet issues

### Quaternary User Journey: Team Message
1. **Trigger:** New message posted in team chat or direct message received
2. **Notification:** Push: "New message from Sarah: 'Can anyone cover tomorrow?'"
3. **Action:** Team member taps "Reply" or notification body to open chat
4. **Confirmation:** App opens to relevant conversation
5. **Retention:** Team feels connected, communication improves

---

## Feature Requirements

### Must Have Features

#### Feature 1: Firebase Cloud Messaging Integration
- **User Story:** As a team member, I want to receive push notifications on my phone so that I stay informed even when the app is closed.
- **Acceptance Criteria:**
  - [ ] App requests notification permission on first launch (iOS/Android)
  - [ ] FCM token is generated and sent to backend on login
  - [ ] Token is refreshed automatically and synced with backend
  - [ ] Notifications are received when app is in background or terminated
  - [ ] Notifications are received when app is in foreground (handled gracefully)
  - [ ] Token is cleared on logout

#### Feature 2: Schedule Notifications
- **User Story:** As a team member, I want to be notified of schedule changes so that I never miss updates to my shifts.
- **Acceptance Criteria:**
  - [ ] Notification sent when a shift is added to my schedule
  - [ ] Notification sent when a shift is modified (time change, location change)
  - [ ] Notification sent when a shift is removed from my schedule
  - [ ] Notification sent as reminder before shift starts (configurable: 1hr, 30min, 15min)
  - [ ] Tapping notification opens schedule screen with relevant date focused

#### Feature 3: Clock/Time Notifications
- **User Story:** As a team member, I want clock reminders so that I never forget to punch in or out.
- **Acceptance Criteria:**
  - [ ] Notification sent when shift is about to start and user hasn't clocked in
  - [ ] Notification sent when shift is about to end as clock-out reminder
  - [ ] Notification sent if user is approaching overtime threshold
  - [ ] Notification sent if a missed punch is detected (e.g., clocked in but never out)
  - [ ] "Clock In" action button works from notification (when within geofence)
  - [ ] "Clock Out" action button works from notification

#### Feature 4: Open Shift Notifications
- **User Story:** As a team member, I want to know when open shifts are available so that I can pick up extra hours.
- **Acceptance Criteria:**
  - [ ] Notification sent when new open shift matches my availability/qualifications
  - [ ] Notification includes shift date, time, and location
  - [ ] "Claim Shift" action button allows claiming directly from notification
  - [ ] Notification sent when my shift claim is approved/denied
  - [ ] Notification sent when a shift I claimed is confirmed

#### Feature 5: Team Chat Notifications
- **User Story:** As a team member, I want to be notified of new messages so that I stay connected with my team.
- **Acceptance Criteria:**
  - [ ] Notification sent for new messages in team chat channels I'm in
  - [ ] Notification sent for direct messages
  - [ ] Notification sent when I'm @mentioned
  - [ ] Message preview shown in notification body
  - [ ] "Reply" action button allows quick response (text input)
  - [ ] Tapping notification opens relevant chat conversation

#### Feature 6: Notification Preferences
- **User Story:** As a team member, I want to control which notifications I receive so that I'm not overwhelmed.
- **Acceptance Criteria:**
  - [ ] Settings screen shows toggle for each notification category
  - [ ] Categories: Schedule, Clock Reminders, Open Shifts, Team Chat
  - [ ] Sub-toggles for reminder timing (1hr, 30min, 15min before shift)
  - [ ] Preferences sync to backend and persist across devices
  - [ ] Changes take effect immediately
  - [ ] Option to mute all notifications temporarily (Do Not Disturb)

### Should Have Features

#### Feature 7: Rich Notification Actions
- **User Story:** As a team member, I want to take action directly from notifications so that I can respond quickly without opening the app.
- **Acceptance Criteria:**
  - [ ] Schedule notifications: "View Schedule" action button
  - [ ] Clock notifications: "Clock In" / "Clock Out" action buttons
  - [ ] Open shift notifications: "Claim Shift" / "View Details" action buttons
  - [ ] Chat notifications: "Reply" action with text input, "Mark Read" action
  - [ ] Actions work from lock screen (with device authentication if required)

#### Feature 8: Notification Grouping
- **User Story:** As a team member, I want related notifications grouped together so my notification shade isn't cluttered.
- **Acceptance Criteria:**
  - [ ] Multiple chat messages from same conversation are grouped
  - [ ] Multiple schedule changes are summarized ("3 schedule updates")
  - [ ] Grouped notifications expand to show individual items
  - [ ] Group summary shows most recent/important item

### Could Have Features

#### Feature 9: Scheduled/Silent Notifications
- **User Story:** As a team member, I want to set quiet hours so I'm not disturbed during off-hours.
- **Acceptance Criteria:**
  - [ ] User can set "quiet hours" (e.g., 10pm-7am)
  - [ ] Notifications during quiet hours are delivered silently
  - [ ] Urgent notifications (e.g., immediate shift changes) can override quiet hours
  - [ ] Per-category quiet hour settings

#### Feature 10: Notification History
- **User Story:** As a team member, I want to see past notifications in the app in case I missed or dismissed one.
- **Acceptance Criteria:**
  - [ ] In-app notification inbox/history screen
  - [ ] Shows all notifications from past 30 days
  - [ ] Notifications marked as read/unread
  - [ ] Can tap to navigate to relevant screen

### Won't Have (This Phase)

- **Manager broadcast notifications**: Managers sending custom messages to all team members (future phase)
- **Location-based notifications**: "You're near the store, want to check in?" (privacy concerns, future evaluation)
- **Notification sounds customization**: Custom sounds per notification type (OS limitations)
- **Cross-device notification sync**: Marking notification read on one device clears on others (complexity)
- **Ably replacement**: This phase uses FCM alongside Ably, not replacing it

---

## Detailed Feature Specifications

### Feature: Clock-In Reminder with Action Button
**Description:** When a team member has a shift starting soon and hasn't clocked in, they receive a push notification with the ability to clock in directly from the notification without opening the app (if within geofence).

**User Flow:**
1. Backend detects shift starting in 15 minutes, user not clocked in
2. Backend sends FCM push with clock-in action
3. User sees notification on lock screen: "Your shift starts in 15 minutes! Clock in now."
4. User taps "Clock In" action button
5. App briefly activates to check geofence
6. If within geofence: Clock-in recorded, confirmation notification sent, Live Activity starts
7. If outside geofence: Notification says "Move closer to your store to clock in"

**Business Rules:**
- Rule 1: Clock-in action only appears if user is within store geofence radius
- Rule 2: Clock-in reminder sent at user's preferred reminder time (default: 15 min before)
- Rule 3: Only one reminder sent per shift (no spam)
- Rule 4: If user clocks in before reminder time, reminder is cancelled
- Rule 5: Reminder not sent if user has "Clock Reminders" disabled in preferences

**Edge Cases:**
- User is outside geofence → Show "View Schedule" action instead of "Clock In"
- User already clocked in → Cancel the reminder notification
- User's shift was cancelled → Cancel the reminder notification
- Network unavailable when action tapped → Queue action, retry when connected, show pending state
- Multiple shifts same day → Send reminder for each shift independently

---

## Success Metrics

### Key Performance Indicators

- **Adoption:**
  - Target: 80% of active users have notifications enabled within 30 days of launch
  - Measure: (Users with FCM token registered) / (Total active users)

- **Engagement:**
  - Target: 60% notification tap-through rate on actionable notifications
  - Measure: (Notifications tapped) / (Notifications delivered)

- **Quality:**
  - Target: <2% notification opt-out rate after initial setup
  - Target: <5% of notifications result in "not relevant" feedback
  - Measure: Users who disable notifications after enabling / Total enabled

- **Business Impact:**
  - Target: 30% reduction in missed clock-ins (comparing pre/post launch)
  - Target: 50% faster open shift claim time (time from post to claim)
  - Target: 25% reduction in "I didn't know about the schedule change" incidents

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `notification_permission_requested` | `granted: bool, platform: string` | Track opt-in rate |
| `notification_permission_changed` | `enabled: bool, source: string` | Track opt-out and re-enable |
| `notification_received` | `type: string, notification_id: string` | Track delivery |
| `notification_tapped` | `type: string, action: string, notification_id: string` | Track engagement |
| `notification_action_completed` | `type: string, action: string, success: bool` | Track action success |
| `notification_dismissed` | `type: string, notification_id: string` | Track dismissals |
| `notification_preference_changed` | `category: string, enabled: bool` | Track preference changes |
| `clock_in_from_notification` | `shift_id: string, within_geofence: bool` | Track clock actions from push |
| `shift_claimed_from_notification` | `shift_id: string, response_time_seconds: int` | Track open shift response |

---

## Constraints and Assumptions

### Constraints
- **Platform limitations:** iOS requires explicit notification permission; Android 13+ requires runtime permission
- **Geofence accuracy:** Location accuracy varies; clock-in action must gracefully handle edge cases
- **Battery impact:** Must minimize background location checks to preserve battery
- **FCM quotas:** Firebase has message rate limits that backend must respect
- **Payload size:** FCM data payload limited to 4KB
- **iOS background limitations:** Background app refresh must be enabled for timely delivery

### Assumptions
- Backend will implement FCM integration to send notifications (this PRD covers mobile app only)
- Backend already has schedule, clock, and open shift data needed to trigger notifications
- Ably remains the primary real-time channel for in-app updates; FCM supplements for background
- Users have modern smartphones capable of receiving push notifications
- Store geofence data is already available in the system

---

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Low notification opt-in rate | High | Medium | Clear value proposition during onboarding, explain benefits before permission prompt |
| Notification fatigue (too many) | High | Medium | Granular preferences, smart defaults, grouping, quiet hours |
| Delayed notification delivery | Medium | Low | Use FCM high-priority for time-sensitive notifications, monitor delivery metrics |
| Clock action fails from notification | Medium | Medium | Clear error messaging, fallback to open app, queue and retry |
| Battery drain from background checks | Medium | Low | Minimize location polling, use geofence APIs efficiently |
| Users miss important notifications if disabled | High | Medium | In-app indicators for unread items, periodic re-engagement prompts |

---

## Open Questions

- [x] Which notification types are needed? → All 4: Schedule, Clock, Open Shifts, Chat
- [x] Who triggers notifications? → Backend handles all notification logic
- [x] FCM vs Ably relationship? → FCM for push (background), Ably for real-time (foreground)
- [x] User preference granularity? → Per-category toggles in app settings
- [x] Rich notifications needed? → Yes, with action buttons

---

## Supporting Research

### Competitive Analysis
- **WhenIWork:** Offers push notifications for schedule changes, shift reminders, open shifts. Users report high value from shift reminders.
- **Homebase:** Push notifications for schedules and time clock. Action buttons for clock-in/out well-received.
- **7shifts:** Rich notifications with quick actions. Notification preferences are granular.

**Key Takeaway:** All major competitors have push notifications as a core feature. Users expect and value this functionality.

### User Research
- Current user feedback indicates frustration with needing to "remember to check the app"
- Manager feedback highlights time spent on phone calls/texts for schedule communication
- Employees express desire to know about open shifts faster than co-workers

### Market Data
- 91% of iOS users and 96% of Android users have push notifications enabled for at least one app
- Retail/service industry apps see 40-60% engagement rates from push notifications
- Timely, relevant notifications have 7x higher engagement than generic ones