# Product Requirements Document

## Validation Checklist

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

---

## Product Overview

### Vision
Enable team members to personalize their identity within the BuyerKiosk Team app by capturing and uploading a profile photo, creating a more engaging and recognizable team experience.

### Problem Statement
Team members using the BuyerKiosk Team app currently see only text initials (e.g., "JD") as their profile representation throughout the app. This impersonal experience:
- **Makes it harder to identify colleagues** in team chat and scheduling views
- **Reduces sense of ownership** and personal connection to their digital workspace
- **Feels dated** compared to modern workforce apps that feature profile photos
- **Limits manager recognition** of team members in schedule views with many employees

The existing codebase has a `photoUrl` field that is never populated or displayed, representing unused potential.

### Value Proposition
By enabling camera-based avatar creation, team members can:
- **Express their identity** with a personal photo they control
- **Recognize teammates instantly** in chat and scheduling contexts
- **Feel more connected** to their digital workspace
- **Maintain consistency** with how they appear in other workplace tools

This feature leverages the device's camera for instant capture, making it frictionless compared to apps that require photo library uploads only.

## User Personas

### Primary Persona: Frontline Team Member
- **Demographics:** Ages 18-45, hourly retail/service worker, moderate smartphone proficiency
- **Goals:** Quickly set up their profile, be recognized by teammates, feel part of the team
- **Pain Points:** Limited time during shifts to configure apps, frustrated by complex setup flows, wants their photo to look good

### Secondary Persona: Store Manager
- **Demographics:** Ages 25-55, manages 5-50+ team members, high smartphone proficiency
- **Goals:** Quickly identify team members in schedules, see who's working at a glance, build team culture
- **Pain Points:** Hard to remember names when teams are large, initials all look similar, wants visual team roster

## User Journey Maps

### Primary User Journey: First-Time Avatar Setup
1. **Awareness:** User notices their profile shows generic initials in Dashboard or Settings
2. **Consideration:** User taps on their avatar (Dashboard Welcome Card OR Settings Profile) and sees option to add photo
3. **Adoption:** User chooses to take a photo with camera (vs. gallery) for convenience
4. **Usage:** User captures photo, previews it, optionally retakes, then confirms upload
5. **Retention:** User sees their photo throughout the app and feels recognized

### Secondary User Journey: Updating Existing Avatar
1. **Awareness:** User decides current photo is outdated or they want a change
2. **Consideration:** User navigates to Settings and taps on their existing avatar
3. **Adoption:** User chooses to take a new photo or remove current photo
4. **Usage:** User captures new photo, confirms replacement
5. **Retention:** Updated photo appears across the app immediately

## Feature Requirements

### Must Have Features

#### Feature 1: Camera Capture
- **User Story:** As a team member, I want to take a photo using my phone's camera so that I can use it as my avatar without leaving the app
- **Acceptance Criteria:**
  - [ ] User can access camera from avatar selection flow (Dashboard or Settings)
  - [ ] Front-facing camera opens by default (selfie mode for profile photos)
  - [ ] Camera preview shows live feed before capture
  - [ ] User can capture photo with single tap
  - [ ] System requests camera permission on first use with clear explanation
  - [ ] If permission denied permanently, show message with link to device Settings
  - [ ] Works on both iOS and Android devices

#### Feature 2: Photo Preview & Confirmation
- **User Story:** As a team member, I want to preview my photo before uploading so that I can ensure I look presentable
- **Acceptance Criteria:**
  - [ ] Preview shows captured photo with circular crop overlay
  - [ ] User can retake photo if unsatisfied (returns to camera)
  - [ ] User can confirm photo to proceed with upload
  - [ ] Preview quality matches final avatar quality

#### Feature 3: Avatar Upload
- **User Story:** As a team member, I want my avatar photo saved to my account so that it persists across sessions and devices
- **Acceptance Criteria:**
  - [ ] Photo uploads to server after confirmation
  - [ ] Upload progress indicator shows during transfer
  - [ ] Success confirmation displayed after upload completes
  - [ ] Avatar immediately displays throughout app after successful upload
  - [ ] Upload failure shows clear error message with retry option

#### Feature 4: Avatar Display
- **User Story:** As a team member, I want to see my avatar photo in the app so that I feel recognized
- **Acceptance Criteria:**
  - [ ] Avatar displays in Settings screen profile section
  - [ ] Avatar displays in any future team views (chat, schedule)
  - [ ] Graceful fallback to initials if no avatar or loading fails
  - [ ] Avatar loads quickly with appropriate caching

### Should Have Features

#### Feature 5: Photo Gallery Selection
- **User Story:** As a team member, I want to choose an existing photo from my gallery so that I can use a photo I already like
- **Acceptance Criteria:**
  - [ ] User can choose between camera and photo gallery
  - [ ] Gallery picker respects platform conventions (iOS Photos, Android Gallery)
  - [ ] Selected photo goes through same preview/confirmation flow
  - [ ] System requests photo library permission with clear explanation

#### Feature 6: Remove Avatar
- **User Story:** As a team member, I want to remove my avatar photo so that I can revert to initials if I prefer
- **Acceptance Criteria:**
  - [ ] Remove option available when avatar exists (in bottom sheet)
  - [ ] Confirmation dialog shown before removal ("Remove your profile photo?")
  - [ ] User must tap "Remove" to confirm or "Cancel" to abort
  - [ ] Immediately reverts to initials display after confirmed removal
  - [ ] Server notified of avatar removal via DELETE endpoint

### Could Have Features

#### Feature 7: Basic Photo Adjustments
- **User Story:** As a team member, I want to make minor adjustments to my photo so that it looks better
- **Acceptance Criteria:**
  - [ ] Pinch to zoom/crop within circular frame
  - [ ] Drag to reposition photo within frame
  - [ ] Changes preview in real-time

### Won't Have (This Phase)

- **Photo filters/effects** - Keep it simple for MVP
- **AI-generated avatars** - Out of scope
- **Avatar history/versioning** - Not needed initially
- **Team avatar gallery** - Future feature for managers
- **Animated avatars/GIFs** - Unnecessary complexity
- **Third-party avatar services** (Gravatar, etc.) - Using our own storage

## Detailed Feature Specifications

### Feature: Camera Capture & Upload Flow

**Description:** The complete flow from initiating avatar capture through successful upload, representing the core user experience.

**User Flow:**
1. User taps avatar in Dashboard (Welcome Card) OR Settings screen (Profile section)
2. System presents bottom sheet with options: "Take Photo", "Choose from Gallery", and "Remove Photo" (if avatar exists)
3. User selects "Take Photo"
4. System checks camera permission
   - If not granted: Show permission request with explanation
   - If denied: Show helpful message directing to Settings
5. Camera opens with front-facing camera active
6. User sees live preview with circular framing guide
7. User taps capture button
8. System shows captured photo in preview with circular crop
9. User can tap "Retake" to return to step 6 or "Use Photo" to continue
10. System shows upload progress indicator
11. On success: System displays success message, avatar updates throughout app
12. On failure: System shows error message with "Retry" option

**Business Rules:**
- Rule 1: Photos must be automatically compressed to reasonable size before upload (max 1MB)
- Rule 2: Photos must be cropped to square aspect ratio (1:1) with circular frame during capture
- Rule 3: Camera permission denial should not block app functionality - just avatar feature
- Rule 4: User must explicitly confirm photo before upload (no auto-upload)
- Rule 5: Avatar update should be reflected immediately in local UI (optimistic update)
- Rule 6: Avatars are visible to all team members (no privacy restrictions)
- Rule 7: No content moderation required - trust team members to use appropriate photos

**Edge Cases:**
- Scenario 1: Camera permission denied → Expected: Show message explaining how to enable in device Settings
- Scenario 2: Upload fails mid-transfer → Expected: Show error with retry option, preserve captured photo
- Scenario 3: User backgrounded during upload → Expected: Complete upload if possible, notify on return
- Scenario 4: Very large photo selected → Expected: Auto-compress to acceptable size
- Scenario 5: No internet connection → Expected: Show offline message, allow retry when connected
- Scenario 6: User cancels during capture → Expected: Return to Settings with no changes

## Success Metrics

### Key Performance Indicators

- **Adoption:** 40% of active users upload an avatar within 30 days of feature launch
- **Engagement:** 80% of users who start capture flow complete the upload
- **Quality:** <5% avatar upload failure rate
- **Satisfaction:** Positive qualitative feedback in app reviews mentioning profile/avatar

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `avatar_flow_started` | `source` (settings, prompt) | Measure interest in feature |
| `avatar_capture_initiated` | `method` (camera, gallery) | Understand preferred capture method |
| `avatar_permission_requested` | `permission_type` (camera, gallery) | Track permission request frequency |
| `avatar_permission_result` | `permission_type`, `granted` (bool) | Measure permission grant rates |
| `avatar_photo_captured` | `method` (camera, gallery) | Track successful captures |
| `avatar_photo_retaken` | `retake_count` | Understand photo satisfaction |
| `avatar_upload_started` | `file_size_kb` | Track upload sizes |
| `avatar_upload_completed` | `duration_ms` | Measure upload performance |
| `avatar_upload_failed` | `error_type` | Identify failure patterns |
| `avatar_removed` | - | Track removal frequency |

---

## Constraints and Assumptions

### Constraints
- **Platform Requirement:** Must work on iOS 12+ and Android API 23+ (existing app minimums)
- **Backend Dependency:** Requires backend API endpoints for avatar upload and retrieval
- **Storage:** Backend must handle image storage (likely S3 or similar)
- **File Size:** Keep uploaded images under 1MB to prevent storage bloat and slow loads

### Assumptions
- Backend team will provide avatar upload endpoint (`/api/mobile/me/avatar`)
- Backend will return `photoUrl` in user data after upload
- Users have cameras on their devices (standard for supported devices)
- Existing `photoUrl` field in user model will be used (already exists but unused)

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Backend API not ready | High | Medium | Coordinate with backend team early, mock API during development |
| Camera permission rejections | Medium | Medium | Clear permission explanation, graceful degradation to initials |
| Large photo uploads slow | Medium | Low | Client-side compression before upload |
| Storage costs increase | Low | High | Implement reasonable file size limits, compress images |
| Privacy concerns | Medium | Low | Clear data handling in privacy policy, option to remove avatar |

## Open Questions

- [x] ~~Will backend handle image compression or should client do it?~~ → Client compresses before upload
- [x] ~~What is the maximum file size the backend will accept?~~ → 1MB limit assumed (confirm with backend team during Phase 1)
- [x] ~~Should we support landscape/portrait photos or only square?~~ → Square only (1:1), forced circular crop during capture
- [x] ~~Are there any content moderation requirements for avatars?~~ → No moderation needed, trust team members
- [x] ~~Should avatar be visible to all team members or only managers?~~ → Visible to all team members

---

## Supporting Research

### Competitive Analysis
**WhenIWork:** Supports profile photos via camera or gallery, displays in schedule and messages. Simple flow similar to proposed design.

**Homebase:** Profile photos supported, used in team directory and schedule views. Includes both camera and gallery options.

**7shifts:** Full avatar support with camera capture, used throughout the scheduling experience to identify team members.

**Key Insight:** All major competitor apps support profile photos with camera capture as a standard feature. Users expect this functionality.

### User Research
Based on common patterns in workforce management apps:
- Profile photos increase engagement and team connection
- Camera capture is preferred over gallery for quick setup during onboarding
- Circular avatars are industry standard for profile representation

### Market Data
- 95%+ of smartphones have front-facing cameras capable of quality selfies
- Profile photo features see 30-50% adoption in workforce apps
- Teams with profile photos report higher communication engagement