# Product Requirements Document: Staff Chat Backend

## 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
Create a unified, private communication hub for each store that centralizes staff communication across all BuyerKiosk platforms - enabling instant collaboration, task visibility, and team cohesion similar to having a private Slack workspace for every store location.

### Problem Statement
Store staff currently lack a centralized, real-time communication channel within the BuyerKiosk ecosystem. Communication happens through fragmented channels:
- Personal text messages between staff
- Phone calls that interrupt workflow
- Verbal handoffs during shift changes (often lost)
- Sticky notes and whiteboards (not accessible remotely)
- External apps (WhatsApp, GroupMe) that create data silos and security concerns

**Consequences of not solving this:**
- Important task updates are missed across shifts
- Managers spend time on phone calls that could be quick messages
- Staff working remotely (BuyerKiosk Team app) feel disconnected
- Sensitive store communications exist on personal devices outside company control
- No audit trail for important decisions or discussions

### Value Proposition
BuyerKiosk Staff Chat provides a secure, integrated communication platform that:
- **Lives where staff already work** - integrated into Team app, Live app, and Workbook
- **Connects tasks to conversations** - when notes/tasks are posted, everyone sees them in chat
- **Respects role boundaries** - managers can have private discussions without separate apps
- **Keeps data in-house** - all communications stored securely within BuyerKiosk infrastructure
- **Works for all access levels** - from the floor (Workbook) to on-the-go (mobile apps)

## User Personas

### Primary Persona: Store Manager (Jordan)
- **Demographics:** 28-45 years old, manages 1-2 store locations, moderate technical expertise
- **Goals:**
  - Keep the team informed without constant phone calls
  - Quickly communicate schedule changes, urgent updates, or kudos
  - Have private discussions with owners about staffing, issues
  - Ensure important messages reach everyone, even across shifts
- **Pain Points:**
  - Spends too much time on phone calls for simple updates
  - Uses personal phone for work group chats (privacy concerns)
  - Shift handoffs lose information
  - Can't verify who has seen important announcements

### Secondary Personas

#### Store Owner (Alex)
- **Demographics:** 35-60 years old, may own multiple locations, varies from hands-on to hands-off
- **Goals:**
  - High-level visibility into store operations
  - Private channel with management for sensitive discussions (staffing, performance)
  - Quick way to broadcast announcements across teams
- **Pain Points:**
  - External apps mix personal and business communication
  - No visibility into team dynamics unless physically present
  - Important decisions discussed verbally with no record

#### Shift Lead (Casey)
- **Demographics:** 22-35 years old, floor-level leadership, high mobile usage
- **Goals:**
  - Coordinate with team during shift
  - Quickly update manager on issues
  - See task assignments without checking multiple places
- **Pain Points:**
  - Has to text manager personally for updates
  - Workbook doesn't allow chatting back
  - Misses context from previous shift discussions

#### Floor Staff (Sam)
- **Demographics:** 18-30 years old, hourly employee, very high mobile usage
- **Goals:**
  - Know what's happening at the store
  - Ask quick questions without calling manager
  - Feel connected to the team
- **Pain Points:**
  - Feels out of the loop
  - Uses personal phone for work group texts
  - Doesn't see task updates unless told verbally

## User Journey Maps

### Primary User Journey: Daily Store Communication

1. **Awareness:** Manager opens Team app in the morning and sees unread messages in the store's public channel, including automated posts about tasks created yesterday
2. **Consideration:** Manager evaluates whether to respond in chat or call - realizes chat is faster and creates a record
3. **Adoption:** Manager posts a quick update about today's priority tasks, mentions @Casey to assign ownership
4. **Usage:** Throughout the day, team members:
   - React with emoji to acknowledge messages
   - Ask clarifying questions
   - Share photos of inventory issues
   - See automated posts when workbook notes are added
5. **Retention:** Manager reviews chat at end of day, sees who read announcements, and feels confident team is aligned

### Secondary User Journeys

#### Private Management Discussion
1. Owner notices an issue in the public channel
2. Opens the "Managers" channel (visible only to manager-level and above)
3. Discusses the issue privately with store manager
4. Agrees on action plan without floor staff seeing the deliberation
5. Manager posts appropriate update to public channel

#### Shift Handoff
1. Outgoing shift lead posts a summary in public channel before leaving
2. Tags incoming shift lead with key items to watch
3. Incoming shift lead reads message, reacts with ✅ to acknowledge
4. Later references the message if questions arise
5. Manager reviews both messages to ensure continuity

#### Workbook User Participation
1. Staff at the kiosk sees public channel on Workbook dashboard
2. Reads announcements and task updates
3. Can post messages or react to existing ones
4. Cannot see private management channels
5. Stays informed without needing mobile app access

## Feature Requirements

### Must Have Features

#### Feature 1: Channels with Role-Based Access
- **User Story:** As a store manager, I want to create channels with specific access levels so that I can have private discussions with appropriate team members
- **Acceptance Criteria:**
  - [ ] Users can only see channels they have access to based on their role
  - [ ] Channel access is automatically updated when employee role changes
  - [ ] Administrators can manually add/remove users from channels as overrides
  - [ ] Each store has a default "public" channel accessible to all store employees
  - [ ] Channel list shows unread message count per channel

#### Feature 2: Message CRUD with Audit Trail
- **User Story:** As a user, I want to send, edit, and delete messages so that I can communicate effectively and correct mistakes
- **Acceptance Criteria:**
  - [ ] Users can send text messages between 1-4000 characters (empty rejected)
  - [ ] Users can edit their own messages within 24 hours of posting; edited messages show "(edited)" suffix
  - [ ] Users can delete their own messages at any time; deleted messages show "This message was deleted" placeholder
  - [ ] Audit log captures: action (create/edit/delete), timestamp, user_id, original content, new content (for edits)
  - [ ] Messages return: message_id, sender_id, sender_name, sender_avatar_url, content, created_at, edited_at (nullable)

#### Feature 3: Image Attachments
- **User Story:** As a user, I want to attach images to messages so that I can share visual information with my team
- **Acceptance Criteria:**
  - [ ] Users can upload images from device (JPEG, PNG, GIF)
  - [ ] Images display inline in the chat
  - [ ] Images can be viewed full-screen
  - [ ] Maximum file size: 10MB per image
  - [ ] Multiple images can be sent in a single message

#### Feature 4: Emoji Reactions
- **User Story:** As a user, I want to react to messages with emojis so that I can acknowledge or respond quickly without typing
- **Acceptance Criteria:**
  - [ ] Users can add any standard Unicode emoji as a reaction to any message
  - [ ] API returns reactions grouped by emoji with list of user_ids who reacted
  - [ ] Users can remove their own reactions; API returns 204 on successful removal
  - [ ] Maximum 20 unique emoji types per message; API returns 400 if limit exceeded
  - [ ] Backend stores emoji as Unicode codepoint; frontend renders from standard emoji set

#### Feature 5: @User Mentions
- **User Story:** As a user, I want to mention specific team members so that they are notified about important messages
- **Acceptance Criteria:**
  - [ ] Typing "@" shows autocomplete list of channel members
  - [ ] Mentioned users receive push notification (if enabled)
  - [ ] Mentioned username is highlighted in message
  - [ ] Users can view all messages where they were mentioned

#### Feature 6: Read Receipts
- **User Story:** As a sender, I want to see who has read my messages so that I know my communication was received
- **Acceptance Criteria:**
  - [ ] API endpoint accepts `lastReadMessageId` to mark channel as read up to that point; returns 204 on success
  - [ ] Channel list returns unread count based on high water mark comparison
  - [ ] Read events published to Ably channel within 500ms of API call
  - [ ] Channel endpoint returns `last_read_message_id` per user for unread count calculation
  - [ ] Read receipts deduplicated: re-reading same position does not create duplicate entry
- **Note:** Per ADR-2, read tracking uses per-channel high water mark (not per-message) for simplicity and performance

#### Feature 7: Event Integration (Tasks & Notes)
- **User Story:** As a user, I want to see workbook tasks and notes in the chat so that important updates are visible to the whole team
- **Acceptance Criteria:**
  - [ ] When a task is created in workbook, a system message appears in the relevant channel
  - [ ] When a note is posted, it appears as a system message in the public channel
  - [ ] System messages are visually distinct from user messages
  - [ ] System messages link back to the original task/note if applicable

#### Feature 8: Push Notifications
- **User Story:** As a user, I want to receive push notifications for new messages so that I stay informed when not actively using the app
- **Acceptance Criteria:**
  - [ ] Users receive Firebase push notifications for new messages
  - [ ] Notifications show sender name and message preview
  - [ ] Users can mute specific channels
  - [ ] @mentions always trigger notification (unless globally disabled)
  - [ ] Notification links open directly to the relevant message

#### Feature 9: Real-Time Updates
- **User Story:** As a user, I want messages to appear instantly so that conversations feel live and responsive
- **Acceptance Criteria:**
  - [ ] Ably message published within 200ms of successful database write
  - [ ] Ably channel per store-channel: `chat:{typeNum}:{channel_id}`
  - [ ] Presence channel for typing: `chat:{typeNum}:{channel_id}:presence`
  - [ ] Event types: `message.created`, `message.updated`, `message.deleted`, `reaction.added`, `reaction.removed`, `read.updated`
  - [ ] Payload includes full message object (no client refetch required for display)

### Should Have Features

#### Feature 10: Message Search
- **User Story:** As a user, I want to search chat history so that I can find past conversations and decisions
- **Acceptance Criteria:**
  - [ ] Users can search messages within a channel
  - [ ] Search returns results with message context
  - [ ] Search highlights matching terms
  - [ ] Results are sorted by relevance/date

#### Feature 11: Configurable Message Retention
- **User Story:** As a store owner, I want to set message retention policies per channel so that I can manage storage and compliance
- **Acceptance Criteria:**
  - [ ] Owners can configure retention period per channel (30/90/365 days, or forever)
  - [ ] Messages are automatically purged after retention period
  - [ ] Users are informed of retention policy in channel info
  - [ ] Default retention is "forever" unless configured

### Could Have Features

#### Feature 12: Pinned Messages
- **User Story:** As a manager, I want to pin important messages so that team members can easily find key information
- **Acceptance Criteria:**
  - [ ] Managers can pin messages to channel
  - [ ] Pinned messages are accessible from channel header
  - [ ] Maximum 10 pinned messages per channel

#### Feature 13: GIF Library Integration
- **User Story:** As a user, I want to send GIFs so that I can add fun to conversations
- **Acceptance Criteria:**
  - [ ] Users can search and send GIFs from integrated library (GIPHY/Tenor)
  - [ ] GIFs display inline in chat
  - [ ] Optional: Disable GIFs per channel setting

### Won't Have (This Phase)

- **Direct Messages (DMs):** All communication through channels only
- **Voice/Video Calls:** Text and images only
- **File Attachments (non-image):** PDFs, documents not supported
- **Threaded Replies:** Flat conversation model
- **Cross-Store Channels:** Channels are store-specific only
- **External User Access:** Only employees can access chat
- **Message Scheduling:** No scheduled/delayed messages
- **Bots/Integrations:** No third-party integrations beyond event posting
- **Message Forwarding:** Cannot forward messages to other channels

## Detailed Feature Specifications

### Feature: Channels with Role-Based Access

**Description:** Channels are the fundamental organization unit for conversations. Each channel belongs to a single store and has an access level that determines which employees can view and participate. The system automatically manages membership based on employee roles while allowing manual overrides for flexibility.

**User Flow:**
1. User opens the chat section of the app/workbook
2. System checks user's store association and role level
3. System displays only channels the user has access to
4. User selects a channel to view/participate
5. System loads messages and subscribes to real-time updates

**Business Rules:**
- Rule 1: Every store has exactly one "Public" channel created automatically
- Rule 2: Only users with manager-level or higher permissions can create new channels
- Rule 3: Channel access level maps to existing user permission system
- Rule 4: When a user's role changes, their channel access updates within 5 minutes
- Rule 5: Manual access overrides persist until explicitly removed
- Rule 6: Workbook users can ONLY see and access the Public channel
- Rule 7: Users terminated/deactivated lose all channel access immediately
- Rule 8: Channel creators automatically have full access to their channel

**Edge Cases:**
- User demoted from manager to staff → Expected: Loses access to manager channels, keeps override access if granted
- User added manually to channel then role upgraded → Expected: Retains access through both mechanisms
- Last admin removed from private channel → Expected: Store owner automatically added as fallback admin
- Employee transferred between stores → Expected: Loses access to old store channels, gains access to new store's public channel

### Feature: Message CRUD with Audit Trail

**Description:** Users can create, read, update, and delete messages. All modifications are logged for accountability. The system maintains an audit trail that is not visible to regular users but accessible to administrators if needed.

**User Flow:**
1. User composes message in input field
2. User taps send → message appears instantly (optimistic UI)
3. To edit: User long-presses own message → selects "Edit" → modifies text → saves
4. To delete: User long-presses own message → selects "Delete" → confirms
5. Edited messages show "(edited)" indicator
6. Deleted messages show "Message was deleted" placeholder

**Business Rules:**
- Rule 1: Only message author can edit or delete their messages
- Rule 2: Messages can be edited within 24 hours of posting
- Rule 3: Messages can be deleted at any time by author
- Rule 4: Audit log captures: original content, edit timestamp, editor ID, previous version
- Rule 5: System messages (event posts) cannot be edited or deleted
- Rule 6: Empty messages cannot be sent
- Rule 7: Messages preserve formatting (line breaks)

**Edge Cases:**
- User edits message while others are viewing → Expected: All viewers see updated content in real-time
- Network failure during send → Expected: Message queued locally, retried when online, user sees "sending" indicator
- User deleted while message pending → Expected: Message still sent if queued, audit shows original author
- Concurrent edits (unlikely but possible) → Expected: Last write wins, all versions in audit log

### Feature: Event Integration (Tasks & Notes)

**Description:** When tasks are created or notes are posted in the workbook, system-generated messages automatically appear in the appropriate chat channel. This ensures important operational updates are visible to the team without requiring manual posting.

**User Flow:**
1. Manager creates a task in workbook
2. System generates a chat message: "📋 Task created: [Task title]"
3. Message appears in public channel (or specified channel if feature extended)
4. Team members see the task notification in their chat feed
5. Users can react to acknowledge but cannot reply to system messages

**Business Rules:**
- Rule 1: Task creation → System message to public channel
- Rule 2: Note creation → System message to public channel
- Rule 3: System messages display differently (styled as "system" not a user)
- Rule 4: System messages include link/reference to original item
- Rule 5: System messages cannot be edited or deleted by users
- Rule 6: System messages count toward retention policy
- Rule 7: No push notifications for system messages (reduces noise)

**Edge Cases:**
- Task created for specific user → Expected: System message mentions the assigned user
- Multiple tasks created in batch → Expected: Individual messages for each (no batching)
- Task deleted immediately after creation → Expected: System message remains as historical record
- Workbook offline when task created → Expected: System message created when workbook reconnects

### Feature: Image Attachments

**Edge Cases:**
- Upload fails mid-transfer → Expected: Return 500 with retry guidance; partial files cleaned up
- File exceeds 10MB → Expected: Return 413 Payload Too Large before processing
- Invalid/corrupted image file → Expected: Return 400 with "Invalid image format" error
- Unsupported format (e.g., HEIC, WebP) → Expected: Return 400 with list of supported formats
- User uploads during message deletion → Expected: Orphaned attachment cleaned up within 1 hour
- Storage disk full → Expected: Return 507 Insufficient Storage; alert operations team

### Feature: Push Notifications

**Edge Cases:**
- User has multiple devices → Expected: Push sent to all registered device tokens
- Firebase token expired/invalid → Expected: Token removed from database; no retry
- User mentioned in channel they've muted → Expected: @mention overrides mute; push sent
- Rapid messages in channel → Expected: Batch notifications with "X new messages" if >3 within 30s
- User viewing channel when message arrives → Expected: No push notification sent (already active)

### Feature: @User Mentions

**Edge Cases:**
- Mention user not in channel → Expected: Mention stored but no notification; username not linkable
- Mention deactivated user → Expected: Mention parsed but no notification; display as plain text
- Edit message to add/remove mention → Expected: Notification sent for added mentions only
- Mention in message that gets deleted → Expected: Original notification already sent; no recall

### Feature: Reactions

**Edge Cases:**
- React to deleted message → Expected: Return 404 "Message not found"
- Same user reacts twice with same emoji → Expected: Idempotent; no duplicate reaction created
- React to message in channel user just lost access to → Expected: Return 403 Forbidden
- Unicode variation selectors (skin tones) → Expected: Store exact codepoint sequence; treat as distinct emoji

### Feature: Read Receipts

**Edge Cases:**
- Mark read with message ID that doesn't exist → Expected: Return 404
- Mark read in inaccessible channel → Expected: Return 403 Forbidden
- Mark read with message ID lower than current high water mark → Expected: No-op, return 204 (idempotent)
- Read receipt for own message → Expected: Allowed (counts as "read" for unread calculation)

### Feature: Message Search

**Edge Cases:**
- Search query too short (<2 chars) → Expected: Return 400 with minimum length requirement
- Search returns 0 results → Expected: Return 200 with empty results array
- Search with special characters → Expected: Escape for database query; prevent injection
- Search deleted messages → Expected: Exclude deleted messages from results

## Success Metrics

### Key Performance Indicators

- **Adoption:** 70% of active store employees send at least one message within 30 days of launch
- **Engagement:** Average 10+ messages per store per day after 60 days
- **Quality:** <1% message delivery failure rate
- **Business Impact:** 20% reduction in manager phone call time (measured via survey)

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `chat_message_sent` | channel_id, message_type, has_attachment, has_mention | Measure engagement and feature usage |
| `chat_message_read` | channel_id, message_id, time_to_read | Calculate read rates and response times |
| `chat_reaction_added` | channel_id, reaction_emoji | Understand reaction patterns |
| `chat_channel_created` | channel_id, access_level, creator_role | Track channel proliferation |
| `chat_channel_viewed` | channel_id, session_duration, messages_viewed | Measure channel engagement |
| `chat_push_notification_opened` | channel_id, notification_type | Track notification effectiveness |
| `chat_message_edited` | channel_id, time_since_send | Understand edit patterns |
| `chat_message_deleted` | channel_id, time_since_send | Understand deletion patterns |
| `chat_image_uploaded` | channel_id, file_size, upload_time | Monitor media usage and performance |
| `chat_mention_sent` | channel_id, mention_count | Track @mention usage |

---

## Constraints and Assumptions

### Constraints
- **Existing Infrastructure:** Must use Firebase for push notifications (already configured)
- **Existing Infrastructure:** Must use Ably for real-time messaging (already configured)
- **Storage:** Media stored locally (not cloud CDN) per user preference
- **Multi-tenant:** Must work within existing multi-store database architecture (per-store databases)
- **Authentication:** Must integrate with existing user permission system
- **Platform Support:** Backend must support web (Workbook), iOS (Team/Live apps), and Android (Team/Live apps)
- **Data Isolation:** Store data must remain isolated; no cross-store channel visibility

### Assumptions
- Users have reliable internet connectivity (at least intermittent)
- Existing user role system provides sufficient granularity for channel access
- Ably's message history feature is adequate for catch-up on reconnect
- Firebase push notification infrastructure can handle additional chat notifications
- Store databases can accommodate new chat tables without performance impact
- <100 messages per day per store (light volume) - architecture can be simpler

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Ably message ordering issues during high load | Medium | Low | Implement server-side message sequencing; Ably handles ordering well for our volume |
| Push notification fatigue leads to disabling | High | Medium | Smart notification batching; channel mute options; @mention-only mode |
| Image storage costs grow unexpectedly | Medium | Low | Implement per-channel retention; set maximum file sizes; monitor storage usage |
| Users confused about channel visibility | Medium | Medium | Clear channel badges showing access level; onboarding tips; help documentation |
| Performance degradation with message history | Medium | Low | Paginated loading; message archival for old channels; index optimization |
| Data privacy concerns with read receipts | Low | Medium | Make read receipts opt-out if feedback requires; clear privacy disclosure |

## Technical Clarifications (SDD Prerequisites)

This section addresses technical ambiguities identified during PRD review that must be understood before solution design.

### Authorization Model

**Role Taxonomy (maps to existing BuyerKiosk permissions):**
| Chat Access Level | Maps To | Can Create Channels | Can Access |
|-------------------|---------|---------------------|------------|
| Owner | `uri_owner` permission | Yes | All channels in owned stores |
| Manager | `uri_store_settings` permission | Yes | All channels in assigned stores |
| Shift Lead | `uri_daybook_edit` permission | No | Public + channels explicitly granted |
| Staff | Basic store access (no special permission) | No | Public channel only |
| Workbook | Authenticated via workbook session | No | Public channel only (read/write) |

**Key Definitions:**
- **"Manager-level"**: Users with `uri_store_settings` permission or higher
- **"Administrator"**: Store-scoped; the user with highest role in that store (Owner > Manager)
- **Store membership**: Determined by existing `user_store_groups` table - users see chat for stores they have access to
- **Multi-store owners**: See separate channel lists per store; no cross-store channels

**Override Precedence:**
1. Explicit channel membership override (highest priority)
2. Role-based automatic access
3. Default public channel access (lowest - everyone gets this)

### Message & Read Semantics

**Message Ordering:**
- **Source of truth**: Database `created_at` timestamp with auto-increment `message_id` for tie-breaking
- **Ably role**: Real-time delivery only; not authoritative for order
- **Client display**: Messages ordered by `message_id` (monotonically increasing per channel)

**Idempotency & Deduplication:**
- Clients generate `client_message_id` (UUID) for each send attempt
- Server deduplicates within 5-minute window using `client_message_id`
- Duplicate sends return success with existing `message_id`

**Read Receipt Semantics:**
- **Per-message tracking**: Each message tracks which users have viewed it
- **"Read" definition**: Message appeared in user's viewport for 1+ seconds while app in foreground
- **Multi-device**: Read status syncs across devices; reading on any device marks as read everywhere
- **Privacy**: Read receipts are visible to all channel members; no opt-out (simplifies v1)

**Delivery Definition (for success metrics):**
- "Delivered" = Message persisted to database AND Ably publish confirmed
- "Read" = Read receipt recorded for that user
- Push notification delivery tracked separately via Firebase analytics

### Storage Model

**Message Storage:**
- **Location**: Per-store database (e.g., `kiosk_ou00.chat_messages`)
- **Rationale**: Maintains existing data isolation; simpler backup/restore per store
- **Scaling**: Adequate for <100 msgs/day; archive strategy needed if volume grows 10x+

**Media Storage:**
- **Location**: Local filesystem at `/var/www/buyerkiosk/uploads/chat/{typeNum}/{channel_id}/{message_id}/`
- **Database**: `chat_attachments` table stores metadata (filename, size, mime_type, path)
- **Access**: Served via authenticated endpoint; URLs are signed with expiring tokens
- **Cleanup**: Attachments deleted when parent message purged by retention policy

**Retention Rules:**
- **Message retention**: Configurable per channel (30/90/365 days or forever)
- **Audit retention**: Separate from message retention; audit logs kept for 2 years minimum
- **Attachment retention**: Tied to message retention (attachment deleted when message purged)
- **Read receipts**: Purged with parent message

### Backend Capabilities (Client-Agnostic)

The following features are described as **backend capabilities**; frontend implementation details are out of scope:

| Feature | Backend Provides | Frontend Responsibility |
|---------|------------------|------------------------|
| Typing indicators | Ably presence channel events | Display/hide indicator UI |
| Optimistic UI | Idempotent message endpoint | Local state management |
| Real-time updates | Ably message events with payload | Subscribe and render |
| Connection status | Ably connection state callbacks | Display indicator |
| Read tracking | API endpoint to record reads | Call API when messages visible |

### Rate Limiting & Abuse Prevention

- **Message rate**: 30 messages per minute per user per channel
- **Attachment rate**: 10 uploads per minute per user
- **Mention rate**: 10 @mentions per message maximum
- **Reaction rate**: 20 reactions per minute per user
- Exceeded limits return HTTP 429 with retry-after header

## Open Questions

- [x] How should channel membership work when employees change levels? → **Hybrid: Auto-sync + manual overrides**
- [x] What message retention policy? → **Configurable per-channel**
- [x] How to handle rich media? → **Store locally, images only**
- [x] Permission integration → **Use existing user roles**
- [x] Event types for auto-posting → **Tasks & Notes only**
- [x] Reaction support → **Yes, emoji reactions**
- [x] Threading model → **Flat conversation**
- [x] Mention types → **@user only**
- [x] Edit/delete support → **Both with audit trail**
- [x] Offline handling → **Firebase push + API fetch**
- [x] Default channel structure → **Single public channel per store**
- [x] Scale design → **Light volume (<100 msgs/day)**
- [x] DM support → **No, channels only**
- [x] File types → **Images only**
- [x] Read receipts → **Yes, show who read**
- [x] API design → **Same endpoints for mobile & workbook**

All major product questions have been resolved.

---

## Supporting Research

### Competitive Analysis

**RMS (Retail Management Systems):**
- Basic chat functionality integrated into POS systems
- Users report it "works but feels dated"
- Limited to text, no rich media or reactions

**Slack/Discord:**
- Gold standard for team communication
- Feature-rich but requires separate app
- Not integrated with retail workflows
- Data lives outside company infrastructure

**Homebase / When I Work:**
- Some team messaging features
- Focused on scheduling, chat is secondary
- Limited channel organization

**BuyerKiosk Differentiators:**
- Deep integration with existing workflows (tasks, notes appear automatically)
- Built into apps staff already use daily
- Role-based privacy respects store hierarchy
- Data stays within BuyerKiosk infrastructure

### User Research

Based on existing user feedback and support tickets:
- **12+ feature requests** for "in-app messaging" or "team chat" in past 12 months
- **~80% of stores** use external apps (WhatsApp, GroupMe) for team communication based on informal survey
- **3 documented incidents** where missed shift handoff communication led to customer complaints
- Managers consistently cite "knowing who saw my message" as #1 desired feature
- Staff want to feel more connected to remote operations

### Market Data

- Retail staff turnover averages 60%+ annually - quick onboarding to communication tools matters
- 67% of retail workers use personal phones for work communication (security concern)
- Team communication apps show 25%+ improvement in employee satisfaction scores