# 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
Transform BuyerKiosk's digital signage from a simple slide-loop system into a flexible, widget-based platform that enables stores to create engaging, multi-zone displays with real-time content, social integration, and intelligent queue management.

### Problem Statement
**Current State:** BuyerKiosk's digital signage system only supports full-screen slides displayed one at a time in a sequential loop. Stores with multiple displays show the same content everywhere, missing opportunities for contextual messaging. Creating engaging content requires external design tools with manual upload workflows. There's no way to show social media presence, weather, or dynamic store information alongside queue displays.

**Pain Points:**
1. **Limited Display Utilization:** Stores with multiple screens (checkout, waiting area, window) must show identical content rather than targeted messaging
2. **Static Queue Experience:** The queue display monopolizes an entire screen, preventing supplementary content
3. **Manual Content Creation:** No integrated design tools - staff must use external software and manually upload
4. **No Social Proof:** Cannot display social media activity to build trust and engagement with waiting customers
5. **Missed Engagement Opportunities:** No way to show weather, events, QR promotions, or "what we're buying" lists dynamically

**Impact:** Stores underutilize their signage investment, miss customer engagement opportunities, and spend excessive time on content management.

### Value Proposition
**For store managers:** Create professional, multi-zone displays in minutes using intuitive templates, real-time widgets, and integrated Canva design tools - no technical expertise required.

**For customers:** Experience informative, engaging signage that provides wait times, store information, social proof, and relevant promotions in a visually appealing format.

**Unique Value:**
- First buy/sell kiosk platform with widget-based signage supporting real-time queue + supplementary content
- Integrated Canva template library for professional designs without leaving the platform
- Social media approval workflow that showcases customer activity safely
- Full QR code tracking for measuring in-store signage ROI

## User Personas

### Primary Persona: Store Manager (Sam)
- **Demographics:** 28-45 years old, manages day-to-day store operations, moderate tech comfort (uses tablets, social media, basic software)
- **Goals:**
  - Keep customers informed and entertained during wait times
  - Promote store services, events, and buying programs
  - Project a professional, modern store image
  - Manage all displays without IT support
- **Pain Points:**
  - Current signage is static and boring after a few visits
  - Creating new content requires design skills they don't have
  - Can't show queue AND promotional content simultaneously
  - Multiple displays all show the same thing - wasteful
  - No way to highlight social media presence in-store

### Secondary Persona: Regional Manager (Rachel)
- **Demographics:** 35-50 years old, oversees 5-15 stores, business-focused, limited time per store
- **Goals:**
  - Ensure brand consistency across all stores
  - Deploy corporate campaigns across multiple locations
  - Track signage effectiveness across the region
  - Empower store managers while maintaining guardrails
- **Pain Points:**
  - No visibility into what individual stores are displaying
  - Can't push corporate content to stores efficiently
  - No analytics on signage engagement (QR scans, etc.)
  - Brand presentation varies wildly between stores

### Tertiary Persona: Corporate Marketing (Maria)
- **Demographics:** 30-40 years old, manages brand assets and campaigns, design-savvy, uses Canva/Adobe tools
- **Goals:**
  - Create branded templates stores can easily use
  - Launch company-wide promotional campaigns
  - Maintain visual brand standards
  - Measure campaign effectiveness
- **Pain Points:**
  - Stores modify corporate content incorrectly
  - No easy way to distribute branded templates
  - Can't track which stores use which content
  - External designers have no access to contribute

### Tertiary Persona: External Designer (Derek)
- **Demographics:** Freelance or agency designer, 25-40 years old, proficient in Canva and design tools
- **Goals:**
  - Create templates for corporate clients efficiently
  - Deliver designs directly to the platform
  - Maintain portfolio of retail signage work
- **Pain Points:**
  - Current workflow requires exporting and emailing files
  - No direct publish mechanism
  - Can't see how designs look in context

## User Journey Maps

### Primary User Journey: Store Manager Creates a Multi-Widget Display Page

1. **Awareness:** Sam sees the new "Signage" menu in the admin nav after system update. Notice prompts highlight new capabilities.

2. **Consideration:** Sam explores the interface, sees template options, and realizes they can now have queue + weather + promotions on one screen.

3. **Adoption:**
   - Sam navigates to Signage → Display Zones → "Waiting Area TV"
   - Views current playlist, clicks "Add Page"
   - Browses template gallery, selects "Header + 2 Columns"
   - Adds "Wait Time Widget" to header zone
   - Adds "Current Queue" to left column, "Weather" to right column
   - Previews in admin, sets duration to 30 seconds
   - Adds to playlist, positions after current queue slide

4. **Usage:**
   - Checks display to verify it's working
   - Over next week, creates additional pages with QR codes and events
   - Approves social media posts that come into the moderation queue
   - Uses Canva templates to create a promotional slide

5. **Retention:**
   - Regularly updates "What We're Buying" widget content
   - Checks QR scan analytics weekly
   - Creates seasonal content using Canva integration
   - Appreciates how easy it is vs. old system

### Secondary User Journey: Regional Manager Deploys Corporate Campaign

1. **Awareness:** Rachel receives notification that corporate uploaded new holiday campaign templates.

2. **Consideration:** Rachel reviews templates in corporate library, checks they meet regional needs.

3. **Adoption:**
   - Navigates to Signage → Corporate Templates
   - Selects holiday campaign template package
   - Chooses "Deploy to Region" option
   - Selects all stores in her region
   - Sets campaign start/end dates
   - Deploys with one click

4. **Usage:**
   - Monitors adoption via dashboard showing which stores have campaign active
   - Reviews basic metrics (play counts) across region
   - Contacts stores that haven't activated campaign

5. **Retention:**
   - Creates region-specific templates for local promotions
   - Uses corporate + custom template mix for optimal results

### Tertiary User Journey: Creating Content via Canva Integration

1. **Awareness:** Sam sees "Create in Canva" button in media library.

2. **Consideration:** Sam explores Canva template gallery showing BuyerKiosk-branded templates sized for signage.

3. **Adoption:**
   - Clicks template to open in Canva
   - Customizes with store name, images, text
   - Clicks "Publish to BuyerKiosk" in Canva
   - Design appears in store's media library

4. **Usage:**
   - Creates multiple slides for different promotions
   - Exports as both image and video (animated)
   - Organizes in folders within media library

5. **Retention:**
   - Uses Canva for most new content creation
   - Builds library of store-specific branded content

### Tertiary User Journey: Social Media Content Moderation

1. **Awareness:** Sam receives notification "3 new social posts pending approval."

2. **Consideration:** Reviews posts in approval queue, checks for appropriateness.

3. **Adoption:**
   - Opens Signage → Social Media → Approval Queue
   - Sees thumbnails and text of pending posts
   - Approves customer photos showing their buys
   - Rejects inappropriate post
   - Approved posts become available for social widgets

4. **Usage:**
   - Checks approval queue daily
   - Configures which hashtags/accounts to monitor
   - Adjusts social widget to show only approved content

5. **Retention:**
   - Customers notice and appreciate being featured
   - Social engagement increases as customers see their content displayed

## Feature Requirements

### Must Have Features

#### Feature 1: Display Zone Management
- **User Story:** As a store manager, I want to configure multiple named display zones so that I can show different content on different screens.
- **Acceptance Criteria:**
  - [ ] Admin can create display zones with predefined names (Checkout, Waiting Area, Window, etc.) or custom names
  - [ ] Each zone has its own independent playlist
  - [ ] Existing single-display stores auto-create one default zone
  - [ ] Zones can be renamed or deleted (with confirmation)
  - [ ] Zone list shows online/offline status of connected displays

#### Feature 2: Layout Template System
- **User Story:** As a store manager, I want to choose from pre-designed layout templates so that I can create multi-widget pages without design skills.
- **Acceptance Criteria:**
  - [ ] Minimum 6 templates available: Full Screen, 50/50 Split, 70/30 Main+Sidebar, 30/70 Sidebar+Main, 3-Column Equal, Header + 2 Columns
  - [ ] Templates are 16:9 aspect ratio (landscape only)
  - [ ] After selecting a template, zones can optionally be resized within template-defined min/max bounds (no freeform layout builder)
  - [ ] Each template zone shows acceptable widget types
  - [ ] Preview shows how template will look before selection
  - [ ] Templates are visually consistent with brand theme

#### Feature 3: Widget Framework
- **User Story:** As a store manager, I want to add various widgets to layout zones so that I can display dynamic, relevant content.
- **Acceptance Criteria:**
  - [ ] Widgets can be added to any compatible template zone
  - [ ] Each widget has a configuration panel for settings
  - [ ] Widgets display live preview in admin during configuration
  - [ ] Widgets respect zone size constraints
  - [ ] Widgets support theme presets (Light, Dark, Brand, Minimal, etc.)

#### Feature 4: Queue Widgets
- **User Story:** As a store manager, I want queue-related widgets so that I can show queue information in various configurations.
- **Acceptance Criteria:**
  - [ ] **Current Queue Widget:** Shows customers currently waiting with names and wait times
  - [ ] **Completed Queue Widget:** Shows recently completed customers
  - [ ] **Wait Time Widget:** Shows estimated wait time prominently
  - [ ] **Full Queue Page Template:** Preset layout with all three (wait time header, current queue left, completed right)
  - [ ] All queue widgets update in real-time via Ably
  - [ ] Queue widgets gracefully handle empty states

#### Feature 5: Media Slide Widgets
- **User Story:** As a store manager, I want to display images and videos on my signage so that I can show promotional content.
- **Acceptance Criteria:**
  - [ ] Image widget supports PNG, JPG, GIF formats
  - [ ] Video widget supports MP4 (any duration)
  - [ ] Media can be selected from unified media library
  - [ ] Images scale to fit zone while maintaining aspect ratio
  - [ ] Videos play with sound muted by default
  - [ ] Existing slides auto-migrate to full-screen media pages

#### Feature 6: Unified Media Library
- **User Story:** As a store manager, I want a centralized media library so that I can organize and reuse content across pages.
- **Acceptance Criteria:**
  - [ ] Upload images and videos with drag-and-drop
  - [ ] Organize media into folders
  - [ ] Search media by name and tags
  - [ ] Bulk upload multiple files
  - [ ] View usage (which pages use each media)
  - [ ] Delete media with warning if in use
  - [ ] Canva integration tab shows Canva-sourced content

#### Feature 7: Playlist Management
- **User Story:** As a store manager, I want to manage the playlist for each display zone so that I can control what plays and in what order.
- **Acceptance Criteria:**
  - [ ] View all pages in playlist with thumbnails
  - [ ] Drag-and-drop reordering
  - [ ] Set duration per page (default 10 seconds, configurable)
  - [ ] Enable/disable pages without removing
  - [ ] Schedule pages with start/expire dates
  - [ ] Simple sequential playback (no complex scheduling rules)

#### Feature 8: Device Registration
- **User Story:** As a store manager, I want displays to connect automatically when possible so that setup is simple.
- **Acceptance Criteria:**
  - [ ] Existing URL pattern (`/typeNum/digitalsign`) continues working
  - [ ] Single-zone stores: device auto-registers to default zone
  - [ ] Multi-zone stores: device shows registration screen with zone selection
  - [ ] Registration uses simple code entry (no QR scanning required)
  - [ ] Admin shows connected devices per zone with last-seen time

#### Feature 9: Offline-First Display Player
- **User Story:** As a store manager, I want displays to keep working when internet is intermittent so that customers always see content.
- **Acceptance Criteria:**
  - [ ] Display caches entire current playlist content
  - [ ] Display continues looping cached content when offline
  - [ ] Display automatically syncs when connection restored
  - [ ] Visual indicator (subtle) when display is offline
  - [ ] Cache refreshes when playlist changes

#### Feature 10: Migration from Legacy System
- **User Story:** As a store manager, I want my existing slides to continue working so that I don't lose content during the upgrade.
- **Acceptance Criteria:**
  - [ ] All existing dsSlides automatically convert to full-screen pages
  - [ ] Existing dsLoop order preserved in new playlist
  - [ ] Existing scheduling (start/expire dates) preserved
  - [ ] Corporate and Hipbone slides remain accessible
  - [ ] No store action required for basic continuity

### Should Have Features

#### Feature 11: Weather Widgets
- **User Story:** As a store manager, I want to show weather information so that customers see useful local information.
- **Acceptance Criteria:**
  - [ ] **Simple Weather Widget:** Current temperature, conditions icon, feels-like temp
  - [ ] **Forecast Weather Widget:** Current conditions + 3-5 day forecast
  - [ ] **Weather Alerts Widget:** Current conditions + severe weather alerts when active
  - [ ] Weather auto-detects from store address
  - [ ] Override option for custom location (ZIP/city)
  - [ ] Updates periodically (configurable, default 30 min)

#### Feature 12: QR Code Widget
- **User Story:** As a store manager, I want to create QR codes with tracking so that I can measure in-store engagement.
- **Acceptance Criteria:**
  - [ ] Create QR code with destination URL
  - [ ] Add promotional text above/below QR code
  - [ ] QR redirects through tracking URL for analytics
  - [ ] Analytics show: total scans, scans by time of day, scans by day of week, which display zone, which page
  - [ ] Visual templates for common uses (Now Hiring, Review Us, Social Follow)

#### Feature 13: Upcoming Events Widget
- **User Story:** As a store manager, I want to show upcoming store events so that customers know about promotions.
- **Acceptance Criteria:**
  - [ ] Pulls from existing event management system
  - [ ] Auto-shows all events marked as public
  - [ ] Shows next 3-5 events with date, time, name
  - [ ] Updates when events change in source system
  - [ ] Graceful empty state when no upcoming events

#### Feature 14: Custom Text Widget (WYSIWYG)
- **User Story:** As a store manager, I want to create custom text content so that I can display any message.
- **Acceptance Criteria:**
  - [ ] Rich text editor with headings, paragraphs, bold, italic
  - [ ] Color options for text and background
  - [ ] Image insertion within text blocks
  - [ ] Multi-column layout options
  - [ ] Preview shows actual rendering
  - [ ] "What We're Buying" template preset using this widget

#### Feature 15: Theme Presets
- **User Story:** As a store manager, I want widgets to have consistent visual styles so that my signage looks professional.
- **Acceptance Criteria:**
  - [ ] Minimum 4 theme presets: Light, Dark, Brand, Minimal
  - [ ] Theme applies to all widgets on a page
  - [ ] Brand theme uses corporate colors/logo
  - [ ] Themes control colors, fonts, backgrounds
  - [ ] Preview shows theme applied before saving

#### Feature 16: Canva Connect Integration
- **User Story:** As a store manager, I want to design content in Canva and publish directly so that I can create professional designs easily.
- **Acceptance Criteria:**
  - [ ] Canva template library accessible from media manager
  - [ ] Templates pre-sized for 16:9 signage format
  - [ ] "Publish to BuyerKiosk" option in Canva sends to media library
  - [ ] Supports both image (PNG) and video (MP4) export
  - [ ] Corporate can contribute branded templates
  - [ ] Store managers can contribute templates (store-level or shared)
  - [ ] External designers can contribute via portal access

#### Feature 17: Social Media Widgets
- **User Story:** As a store manager, I want to display social media content so that I can showcase social proof.
- **Acceptance Criteria:**
  - [ ] **Store Feed Widget:** Shows store's own Facebook, Instagram, or TikTok posts
  - [ ] **Customer Mentions Widget:** Shows posts tagging store or using store hashtags
  - [ ] Both widgets require store-level approval before display
  - [ ] Approval queue shows pending posts with preview
  - [ ] Approved posts cycle through widget
  - [ ] Posts can be removed from approved list

#### Feature 18: Basic Analytics
- **User Story:** As a store manager, I want to see how my signage is performing so that I can optimize content.
- **Acceptance Criteria:**
  - [ ] Page play counts (how many times each page displayed)
  - [ ] Duration displayed (total time each page shown)
  - [ ] QR scan counts with full attribution (time, zone, page)
  - [ ] Display uptime (% time online vs offline)
  - [ ] Simple dashboard view in Signage admin

#### Feature 19: Corporate Template System
- **User Story:** As a regional/corporate manager, I want to create and distribute templates to stores so that I can ensure brand consistency.
- **Acceptance Criteria:**
  - [ ] Corporate users can create page templates
  - [ ] Templates can be pushed to all stores or selected stores
  - [ ] Stores can use corporate templates as-is or as starting points
  - [ ] Corporate can set brand colors and logo applied to Brand theme
  - [ ] Corporate templates appear in store's template library

### Could Have Features

#### Feature 20: Advanced Weather Alerts
- **User Story:** As a store manager, I want severe weather to automatically appear on displays so that customers are informed of safety concerns.
- **Acceptance Criteria:**
  - [ ] Severe weather alerts auto-interrupt normal loop
  - [ ] Alert displays prominently across all zones
  - [ ] Alert auto-dismisses when weather service removes it
  - [ ] Admin can manually dismiss alerts if needed

#### Feature 21: A/B Testing for Content
- **User Story:** As a store manager, I want to test different content versions so that I can optimize engagement.
- **Acceptance Criteria:**
  - [ ] Create A/B variants of a page
  - [ ] System rotates variants evenly
  - [ ] Analytics show performance comparison
  - [ ] "Winner" can be promoted to full rotation

#### Feature 22: Scheduled Playlists
- **User Story:** As a store manager, I want different playlists at different times so that I can show contextual content.
- **Acceptance Criteria:**
  - [ ] Define time-based rules (morning vs afternoon)
  - [ ] Define day-based rules (weekday vs weekend)
  - [ ] System automatically switches playlists
  - [ ] Override option for manual control

#### Feature 23: Display Screenshot Capture
- **User Story:** As a store manager, I want to see what's on each display remotely so that I can verify content.
- **Acceptance Criteria:**
  - [ ] Take on-demand screenshot of any connected display
  - [ ] Automatic periodic screenshots (every 30 seconds)
  - [ ] View recent screenshots in admin
  - [ ] Alert when display shows error/blank

### Won't Have (This Phase)

1. **Freeform drag-and-drop visual layout builder** - Using templates with constrained resizing for simpler UX
2. **Portrait mode (vertical) displays** - Landscape 16:9 only for initial release
3. **Native display apps (iOS/Android/Windows)** - Browser-based player only
4. **Live video streaming** - Pre-recorded video only
5. **Real-time display preview in admin** - Deferred, will show static preview only
6. **AI-powered content recommendations** - Manual content selection only
7. **Multi-language widget content** - Single language per store
8. **Audio announcements** - Video has audio but no standalone audio widgets
9. **Interactive touchscreen features** - Display-only, no touch input
10. **Complex scheduling rules (dayparting, rules engine)** - Simple sequential playlist only

## Detailed Feature Specifications

### Feature: Widget Framework

**Description:** The widget framework is the core system enabling flexible, modular signage pages. It allows any supported widget type to be placed in any compatible layout zone, configured with specific settings, and rendered consistently with theme support.

**User Flow:**
1. User creates new page or edits existing page
2. User selects layout template (e.g., "Header + 2 Columns")
3. System displays template with empty zones showing "+ Add Widget" prompts
4. User clicks zone → widget picker appears showing compatible widget types
5. User selects widget type (e.g., "Current Queue")
6. Widget configuration panel slides in with settings
7. User configures widget (data source, styling, theme)
8. Live preview updates in zone as settings change
9. User saves widget → zone shows populated widget
10. User repeats for other zones or saves page

**Business Rules:**
- Rule 1: Each zone can contain exactly one widget
- Rule 2: Widgets must fit within zone dimensions (no overflow)
- Rule 3: Widgets inherit page theme unless explicitly overridden
- Rule 4: Real-time widgets (queue) must connect to Ably on page load
- Rule 5: Widgets with external data (weather, social) cache data client-side
- Rule 6: Widget configuration is stored per-page, not globally

**Edge Cases:**
- Empty zone: Display subtle placeholder graphic (not blank)
- Widget load failure: Show widget-type icon with "Loading..." message
- External API failure: Show cached data with "Last updated X ago" notice
- Zone too small for widget: Warn user during selection, prevent placement
- Theme incompatible with widget: Apply nearest fallback theme

### Feature: Social Media Approval Workflow

**Description:** Social media content from store feeds or customer mentions flows through an approval queue before appearing on displays, ensuring brand safety and content quality.

**User Flow:**
1. System periodically fetches new posts from configured social accounts/hashtags
2. New posts appear in Signage → Social → Approval Queue
3. Store manager sees thumbnail, post text, author, timestamp
4. Manager clicks "Approve" or "Reject" for each post
5. Approved posts move to "Approved Library"
6. Social widgets display posts from Approved Library
7. Manager can later remove posts from Approved Library

**Business Rules:**
- Rule 1: Posts never display until explicitly approved
- Rule 2: Rejected posts are hidden but can be un-rejected
- Rule 3: Approval is per-store (not global)
- Rule 4: Posts expire after 30 days unless marked "keep"
- Rule 5: Maximum 50 approved posts per widget type
- Rule 6: Posts display in reverse chronological order (newest first)

**Edge Cases:**
- API rate limit hit: Queue shows "Sync paused, will retry" message
- Account disconnected: Alert manager, widget shows last approved content
- Post deleted at source: Remove from approved library automatically
- Inappropriate content approved: Manager can remove at any time
- No approved posts: Widget shows "Follow us @store" placeholder

### Feature: Offline-First Display Architecture

**Description:** Display devices cache all content needed to run independently, ensuring continuous operation during network outages while synchronizing when connectivity returns.

**User Flow:**
1. Display loads page from server on initial connection
2. System caches all playlist pages and media assets locally
3. Display operates from cache, checking for updates periodically
4. If network fails, display continues from cache indefinitely
5. When network returns, display syncs any playlist changes
6. Updated content downloads in background
7. Display transitions to new content seamlessly

**Business Rules:**
- Rule 1: Cache entire current playlist (all pages, all media)
- Rule 2: Cache validation check every 60 seconds when online
- Rule 3: If cache invalid and offline, continue with stale cache
- Rule 4: Real-time widgets (queue) show "Offline" state when disconnected
- Rule 5: Non-real-time widgets show cached data
- Rule 6: Sync priority: playlist structure → new media → updated media

**Edge Cases:**
- Cache storage full: Evict oldest unused media first
- Corrupted cache: Re-download from server on next connection
- Playlist changed while offline: Full sync on reconnection
- Very large video added: Download in chunks, show placeholder until ready
- First-time setup offline: Cannot operate, show "Waiting for connection"

## Success Metrics

### Key Performance Indicators

- **Adoption:**
  - 60% of stores create at least one multi-widget page within 30 days of launch
  - 40% of stores configure multiple display zones within 90 days

- **Engagement:**
  - Average pages per playlist increases from 5 to 12+
  - Widget variety per store averages 4+ different widget types used
  - Canva integration used by 30% of stores within 60 days

- **Quality:**
  - Display uptime > 99% (offline events < 1% of time)
  - Social media approval queue processed within 24 hours
  - Zero content display errors reported per week per store

- **Business Impact:**
  - QR code scans average 50+ per store per month
  - Customer satisfaction (if surveyed) mentions signage positively
  - Reduced support tickets related to signage management

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| page_created | page_id, template_type, widget_types[], zone_count | Track template and widget popularity |
| page_displayed | page_id, zone_id, duration_ms, display_id | Calculate page play counts and duration |
| widget_configured | widget_type, settings_changed[], theme | Understand widget usage patterns |
| qr_scanned | qr_id, page_id, zone_id, timestamp, redirect_url | Full QR attribution analytics |
| media_uploaded | media_id, source (local/canva), file_type, size_bytes | Track Canva adoption and media volume |
| social_post_approved | post_id, platform, approval_latency_hours | Monitor moderation workflow |
| display_connected | display_id, zone_id, auto_vs_manual_registration | Track device setup flow |
| display_offline | display_id, offline_duration_seconds | Monitor reliability |
| playlist_updated | zone_id, pages_added, pages_removed, pages_reordered | Track content management activity |
| canva_template_used | template_id, contributor_type (corp/store/designer) | Track template adoption |

---

## Constraints and Assumptions

### Constraints
- **Browser-based displays:** Must work in modern browsers (Chrome, Firefox, Edge) - no native apps
- **Existing infrastructure:** Must integrate with existing Ably real-time system for queue updates
- **Multi-store architecture:** Must work with existing typeNum/store database structure
- **16:9 landscape only:** No portrait mode support in this phase
- **External API dependencies:** Weather, social media features dependent on third-party API availability and rate limits
- **Canva approval process:** Public Canva Connect integration requires Canva review/approval

### Assumptions
- Stores have reliable internet most of the time (offline is edge case, not norm)
- Store managers are comfortable using web-based admin interfaces
- Corporate already has Meta developer account for social API access
- Stores will adopt gradually - not all stores will use all features immediately
- Existing display hardware is capable of running modern browser
- Canva Connect API supports our integration requirements (validated via documentation)

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Canva API approval takes too long | High | Medium | Start approval process early; have manual upload fallback |
| Social media API rate limits hit | Medium | Medium | Implement aggressive caching; batch requests; respect rate limits |
| Stores overwhelmed by feature complexity | Medium | Medium | Provide guided setup wizard; default templates; contextual help |
| Display hardware can't handle new player | High | Low | Test on known store devices early; provide minimum specs |
| Weather API service disruption | Low | Low | Multi-provider fallback; cached data display |
| Migration breaks existing setups | High | Low | Extensive testing; staged rollout; instant rollback capability |
| Corporate vs store content conflicts | Medium | Medium | Clear ownership rules; conflict resolution in admin |
| Offline cache storage limits on displays | Medium | Medium | Implement cache management; warn on large media |

## Open Questions

- [x] Canva Connect API feasibility - **Confirmed feasible via documentation review**
- [x] Social media API access requirements - **Have Meta account, need TikTok**
- [ ] Weather API provider selection - Research needed for best reliability/cost option
- [ ] Corporate Canva Enterprise license - Required for private integration without Canva review?
- [ ] Display hardware baseline - What are the minimum specs stores are running?
- [ ] TikTok API developer account - Need to set up before implementation

---

## Supporting Research

### Competitive Analysis

**Digital signage market leaders (Scala, Four Winds Interactive, Yodeck):**
- All support multi-zone layouts with widget systems
- Most use drag-and-drop builders (complex) or templates (simpler)
- Social media integration is common but often requires separate subscription
- Weather widgets are standard feature
- QR code tracking is emerging capability

**BuyerKiosk differentiation:**
- First-party queue integration (unique to buy/sell industry)
- Event system integration (promotional campaigns)
- Multi-store corporate/franchise architecture
- Canva integration for accessible design tools

### User Research

**Based on stakeholder input:**
- Store managers want simplicity over flexibility
- Queue display is the most-used feature and must not be compromised
- "What We're Buying" messaging is high priority for customer engagement
- Social proof (customer mentions) is desired but brand safety is paramount
- Multiple displays per store is common (checkout, waiting area, window)

### Market Data

- Digital signage market growing 7-8% annually
- Retail segment is largest adopter
- 70% of consumers say digital signage influences purchasing decisions
- Average attention span for signage content: 8-12 seconds
- QR code usage increased 300% post-pandemic
- Social media displays increase customer engagement by 25-35%

---

*Document version: 1.0*
*Last updated: 2025-12-19*
*Status: Complete - Ready for SDD*