# 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
Enable any prospective client to experience BuyerKiosk as if they're running their own resale store, generating qualified leads through an immersive, self-guided demo that showcases our system's power without requiring sales team involvement.

### Problem Statement
**Current State:** Sales demonstrations of BuyerKiosk require scheduled calls with the sales team, access to sensitive production data, or static screenshots that fail to convey the system's dynamic nature. This creates friction in the sales process:
- **Lost Opportunities:** Conference attendees and website visitors can't explore the product on their own time
- **Sales Bottleneck:** Every demo requires human coordination, limiting scalability
- **Data Risk:** Showing production stores risks exposing real customer data to prospects
- **Stale Impressions:** Static demos don't convey the "living, breathing" nature of a busy resale store

**Evidence:** Current demo process requires scheduling, averaging 3-5 day lead time. Conference leads go cold. Competitors offer self-service demos. No way to capture leads after-hours or at events.

### Value Proposition
**For prospective clients:** Experience exactly what it's like to manage a resale store with BuyerKiosk—see real-time buy queues, manage backstock, schedule staff, and run events—all without commitment, registration friction, or waiting for a sales call.

**For BuyerKiosk:** Capture qualified leads 24/7, scale demo capacity infinitely, eliminate data security concerns, and reduce sales team overhead for initial demonstrations.

---

## User Personas

### Primary Persona: Store Owner/Operator - "Decision-Making Dana"
- **Demographics:** Age 35-55, owns or manages 1-5 resale store locations, moderate technical expertise, time-constrained
- **Goals:**
  - Evaluate if BuyerKiosk solves her operational pain points
  - Compare to current POS/management system
  - Get buy-in from partners/investors before committing
- **Pain Points:**
  - Current systems are fragmented (separate POS, scheduling, inventory)
  - Can't easily see demos of enterprise software without sales pressure
  - Needs to evaluate during non-business hours when she has time

### Secondary Persona: Franchise Development Manager - "Scaling Sam"
- **Demographics:** Age 30-45, evaluates technology for multi-location franchise networks, high technical expertise
- **Goals:**
  - Assess scalability across multiple locations
  - Evaluate training/onboarding complexity for store managers
  - Generate ROI projections for franchise owners
- **Pain Points:**
  - Needs to see the same demo multiple times with different stakeholders
  - Wants to share access with colleagues without coordinating schedules

### Secondary Persona: Conference Attendee - "Curious Chris"
- **Demographics:** Age 25-50, attending retail/resale trade show, varying technical expertise, high time pressure
- **Goals:**
  - Quickly assess if BuyerKiosk is worth deeper evaluation
  - Capture information to review later when back at the office
  - Compare multiple vendors efficiently
- **Pain Points:**
  - Limited time at booth (2-3 minutes typically)
  - Can't remember details from brief conversations
  - Needs something tangible to take back

---

## User Journey Maps

### Primary User Journey: Conference Discovery
1. **Awareness:** Chris visits BuyerKiosk booth at trade show; sees QR code prominently displayed
2. **Consideration:** Scans QR code on phone; immediately enters email on landing page
3. **Adoption:** Receives magic link instantly; chooses store concept (Plato's, OUAC, Style Encore); enters demo
4. **Usage:** Follows guided tour of key features; explores workbook, buy queue, scheduling; sees live simulated activity
5. **Retention:** Returns to demo from hotel that night; shows business partner; clicks "Schedule a Call" CTA

### Secondary User Journey: Website Exploration
1. **Awareness:** Dana finds BuyerKiosk through Google search for "resale store management software"
2. **Consideration:** Lands on website; sees "Try Demo" button prominently displayed
3. **Adoption:** Enters email; receives magic link; selects her store concept
4. **Usage:** Spends 30 minutes exploring at her own pace after store closes; completes full guided tour
5. **Retention:** Returns next day to show store manager; they explore scheduling together; submits contact form

### Secondary User Journey: Sales Follow-up
1. **Awareness:** Sam receives personalized QR code from sales rep after initial call
2. **Consideration:** Shares demo link with three regional managers
3. **Adoption:** Each manager accesses demo independently; Sam tracks their engagement via sales dashboard
4. **Usage:** Team discusses specific features over Zoom while all viewing the demo
5. **Retention:** Sam schedules implementation planning call based on team consensus

---

## Feature Requirements

### Must Have Features

#### Feature 1: Secure Demo Environment
- **User Story:** As a prospective client, I want to explore a fully functional demo that looks and feels like a real store so that I can evaluate the system accurately.
- **Acceptance Criteria:**
  - [ ] Demo runs on isolated subdomain (demo.buyerkiosk.com)
  - [ ] No production data is accessible from demo environment
  - [ ] Demo data is completely separate from production databases
  - [ ] All three store concepts (pc, ou, se) available with appropriate theming
  - [ ] Demo environment uses same codebase with environment-specific configuration

#### Feature 2: Magic Link Access
- **User Story:** As a conference attendee, I want to instantly access the demo with minimal friction so that I can start exploring immediately after scanning a QR code.
- **Acceptance Criteria:**
  - [ ] QR code leads to simple landing page with email capture
  - [ ] Email is required (serves as lead capture)
  - [ ] Magic link sent within 10 seconds of submission
  - [ ] Magic link provides 24-hour access from first click
  - [ ] No password creation required
  - [ ] User can request new magic link if previous expired

#### Feature 3: Store Concept Selection
- **User Story:** As a store owner, I want to choose which store concept (Plato's Closet, Once Upon A Child, Style Encore) to demo so that I see relevant merchandise categories and branding.
- **Acceptance Criteria:**
  - [ ] Selection screen appears after first magic link click
  - [ ] Visual cards show each concept with recognizable branding
  - [ ] Selection persists for the 24-hour session
  - [ ] User can switch concepts without losing session

#### Feature 4: Continuous Live Simulation
- **User Story:** As a prospective client, I want to see realistic store activity happening in real-time so that I can understand how the system works during actual operations.
- **Acceptance Criteria:**
  - [ ] Buy queue shows new customers arriving during simulated business hours
  - [ ] Customers progress through queue stages realistically
  - [ ] Backstock shows items aging with appropriate status indicators
  - [ ] Schedule reflects realistic employee shifts
  - [ ] Activity matches seasonal patterns for the selected concept

#### Feature 5: Session-Scoped User Actions
- **User Story:** As a demo user, I want to make changes (complete a buy, add a task, etc.) without affecting other users' experience so that I can freely experiment.
- **Acceptance Criteria:**
  - [ ] User's writes are isolated to their session
  - [ ] User sees their changes merged with live simulation data
  - [ ] Other concurrent demo users don't see each other's changes
  - [ ] All user changes are discarded when session ends
  - [ ] Clear indicator shows this is a demo environment

#### Feature 6: Interactive Guided Tour (Flows.sh)
- **User Story:** As a first-time visitor, I want a guided walkthrough of key features so that I understand the system's capabilities without getting lost.
- **Acceptance Criteria:**
  - [ ] Tour launches automatically on first visit (can be dismissed)
  - [ ] Tour covers: Workbook, Buy Queue, Admin Dashboard, Events, Backstock, Scheduling
  - [ ] Each step highlights the relevant UI element with explanation
  - [ ] User can skip tour and explore freely
  - [ ] Tour progress is saved (user can resume where they left off)
  - [ ] Tour completion triggers CTA for sales contact

#### Feature 7: QR Code Generation
- **User Story:** As a sales team member, I want to generate QR codes for events so that I can track which conferences drive demo engagement.
- **Acceptance Criteria:**
  - [ ] Static QR code available for general use (links to demo.buyerkiosk.com)
  - [ ] Admin can create event-specific QR codes with tracking tags
  - [ ] Event QR codes track source in analytics
  - [ ] QR codes are downloadable in high resolution for printing

#### Feature 8: Lead Capture & CTAs
- **User Story:** As a BuyerKiosk sales rep, I want demo users to have clear paths to contact sales so that interested prospects convert to sales conversations.
- **Acceptance Criteria:**
  - [ ] Email captured at entry serves as lead
  - [ ] "Schedule a Demo" CTA visible throughout demo (non-intrusive placement)
  - [ ] CTA opens calendar scheduling or contact form
  - [ ] End-of-tour prompt offers sales follow-up
  - [ ] Lead data includes: email, concept selected, pages viewed, tour completion

### Should Have Features

#### Feature 9: Full Funnel Analytics
- **User Story:** As a marketing team member, I want detailed analytics on demo usage so that I can optimize the demo experience and measure ROI.
- **Acceptance Criteria:**
  - [ ] Track: session starts, page views, time on page, feature interactions
  - [ ] Track: tour step completion, tour abandonment points
  - [ ] Track: CTA clicks, form submissions, QR source attribution
  - [ ] Analytics dashboard accessible to authorized users
  - [ ] Data exportable for integration with marketing tools

#### Feature 10: Demo Environment Dashboard
- **User Story:** As an admin, I want to monitor demo environment health and usage so that I can ensure it's working correctly for prospects.
- **Acceptance Criteria:**
  - [ ] View active demo sessions count
  - [ ] View simulation status (running/paused/error)
  - [ ] View recent leads captured
  - [ ] Ability to manually trigger simulation reset if needed

### Could Have Features

#### Feature 11: Personalized Demo Paths
- **User Story:** As a returning demo user, I want a personalized experience based on my interests so that I can dive deeper into relevant features.
- **Acceptance Criteria:**
  - [ ] Track which features user explored most
  - [ ] Suggest unexplored features on return visit
  - [ ] Allow user to "favorite" features for later discussion

#### Feature 12: Comparison Mode
- **User Story:** As an evaluating decision-maker, I want to see side-by-side comparisons with common alternatives so that I can make an informed decision.
- **Acceptance Criteria:**
  - [ ] Feature comparison matrix available
  - [ ] Highlights BuyerKiosk differentiators
  - [ ] Links to relevant case studies

#### Feature 13: Video Walkthroughs
- **User Story:** As a visual learner, I want optional video explanations so that I can see features demonstrated by experts.
- **Acceptance Criteria:**
  - [ ] Embedded videos on key feature pages
  - [ ] Videos playable within demo context
  - [ ] Videos showcase real usage scenarios

### Won't Have (This Phase)

- **Live Chat Support:** No real-time support during demo; rely on CTAs and self-service
- **Account Creation:** No persistent user accounts; magic links only for MVP
- **Custom Demo Data:** Cannot upload own data; uses pre-configured simulation
- **Multi-Language Support:** English only for initial launch
- **Full Dashboard Mobile Optimization:** The landing page + email capture flow must work well on mobile (QR code entry), but in-demo admin screens are desktop-first for MVP
- **POS Integration Demo:** External integrations shown as mockups only
- **Full Report Generation:** Reports shown with sample data, not generated on-demand
- **Outbound Operational Notifications:** No customer-facing SMS/email/push notifications from the demo environment (only the magic link email to the demo user)

---

## Detailed Feature Specifications

### Feature: Session-Scoped User Actions (Shadow Tables)

**Description:** When a demo user takes an action that would normally write to the database (e.g., completing a buy, adding a task), the write goes to session-scoped "shadow" tables instead of the baseline demo data. Reads merge the baseline data with the user's shadow data, creating a personalized view. This allows multiple concurrent users to explore independently while the continuous simulation runs on the baseline.

**User Flow:**
1. User logs into demo with magic link → Session ID generated
2. User views buy queue → System reads baseline demo data
3. User completes a buy → Write goes to shadow table with session_id
4. User views buy queue again → System merges baseline + user's shadow data
5. Another user views buy queue → They see only baseline (not first user's changes)
6. Session expires (24 hours) → Shadow data for that session is purged

**Business Rules:**
- Rule 1: All write operations in demo environment go to shadow tables, never baseline
- Rule 2: Read operations merge baseline + session-specific shadow data
- Rule 3: Shadow data expires when session expires (24 hours from first access)
- Rule 4: Simulation (MockDataGenerator) only writes to baseline, never to shadow
- Rule 5: Shadow tables exist for: buys, customers, tasks, events, notes, schedules

**Edge Cases:**
- Scenario 1: User tries to delete baseline data → Shadow table marks it as "deleted" for this session only; others still see it
- Scenario 2: Simulation adds data while user is active → User sees new simulation data merged with their changes
- Scenario 3: User's session expires mid-activity → Redirected to magic link request page
- Scenario 4: Multiple browser tabs open → Share same session, see same shadow data

### Feature: Interactive Guided Tour

**Description:** On first visit, users are greeted with an optional interactive tour powered by Flows.sh. The tour walks through the major features with step-by-step highlights, explanations, and wait points for user action.

**User Flow:**
1. User enters demo for first time → Tour overlay appears: "Would you like a guided tour?"
2. User clicks "Start Tour" → First step highlights Workbook navigation
3. User clicks highlighted element → Tour progresses to next step
4. User can click "Skip Tour" at any time → Tour dismissed, user explores freely
5. User returns later → Tour resumes from last completed step (or offers to restart)
6. User completes tour → CTA modal: "Ready to see how this works for your store?"

**Business Rules:**
- Rule 1: Tour auto-launches only on first visit (tracked via session)
- Rule 2: Tour progress persists within the 24-hour session
- Rule 3: Tour consists of 6 major sections (can exit/resume between sections)
- Rule 4: Each section has 3-5 steps
- Rule 5: "Wait" steps pause until user performs specific action

**Edge Cases:**
- Scenario 1: User closes browser mid-tour → Tour progress saved; resumes on return
- Scenario 2: User navigates away during tour step → Tour follows or pauses with "return to tour" option
- Scenario 3: User on small screen → Tour adapts with smaller tooltips (but not fully mobile-optimized)

---

## Success Metrics

### Key Performance Indicators

- **Adoption:** 100+ unique demo sessions per month within 3 months of launch
- **Engagement:** Average session duration of 10+ minutes
- **Tour Completion:** 40%+ of users complete at least 3/6 tour sections
- **Conversion:** 15%+ of demo users submit contact form or schedule call
- **Quality:** <1% of sessions experience errors or simulation failures
- **Business Impact:** 10% increase in qualified leads from conference events

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| demo_session_start | email, source (qr_code_id), concept_selected, timestamp | Track demo entry and lead capture |
| page_view | page_path, session_id, time_on_page | Understand feature engagement |
| feature_interaction | feature_name, action_type, session_id | Identify most valuable features |
| tour_step_view | step_id, section_name, session_id | Measure tour progress |
| tour_step_complete | step_id, time_spent, session_id | Identify friction points |
| tour_abandon | step_id, section_name, session_id | Find improvement opportunities |
| cta_click | cta_type, page_path, session_id | Track sales interest |
| contact_form_submit | email, company_name, phone (optional), session_id | Capture conversion |
| session_end | duration, pages_viewed, tour_progress, session_id | Overall engagement |
| simulation_error | error_type, component, session_id | Monitor system health |

---

## Constraints and Assumptions

### Constraints
- **Separate Infrastructure:** Demo must run on isolated subdomain with separate database; cannot share production resources
- **Same Codebase:** Must use existing codebase with environment flags to minimize maintenance burden
- **Flows.sh Commercial:** Budget must accommodate Flows.sh licensing for interactive tour
- **24-Hour Sessions:** Session must expire to prevent indefinite resource consumption
- **Email Required:** Lead capture is non-negotiable; email must be captured for every demo access

### Assumptions
- **Existing MockDataGenerator Works:** Current mock data infrastructure (MockDataGenerator, SeasonalConfig, FakerPHP) is sufficient for demo simulation
- **TaskEngine Available:** TaskEngine can run MockDataGenerator jobs on the demo environment
- **Store Concepts Consistent:** PC, OU, SE concepts have sufficient theming and data differentiation
- **Email Deliverability:** Magic link emails will be deliverable (may need SendGrid or similar)
- **Subdomain Available:** demo.buyerkiosk.com is available and configurable

---

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Demo environment drifts from production (code divergence) | High | Medium | Use same codebase with environment flags; automated testing covers demo mode |
| Simulation data looks "fake" or unconvincing | High | Medium | Leverage historical SeasonalConfig data; user testing before launch |
| Magic link emails go to spam | High | Medium | Use reputable email service; warm up domain; provide "resend" option |
| Shadow table complexity causes bugs | Medium | Medium | Thorough testing of merge logic; clear documentation; fallback to read-only mode |
| Flows.sh integration more complex than expected | Medium | Low | Prototype early; have Shepherd.js as backup option |
| Users exploit demo to stress-test/abuse system | Low | Low | Rate limiting; session caps; monitoring alerts |
| Conference Wi-Fi unreliable for magic link delivery | Medium | Medium | Provide printed backup access codes at booth; offline-friendly landing page |

---

## Open Questions

- [x] Subdomain confirmed: demo.buyerkiosk.com (assumed available)
- [x] Flows.sh budget approved for commercial license
- [x] Shadow table approach vs. alternatives (selected: shadow tables)
- [ ] Email service for magic links (SendGrid? Mailgun? Existing Twilio?)
- [ ] Analytics platform integration (build internal? GA? Mixpanel?)
- [ ] Calendar scheduling tool for CTA (Calendly? HubSpot? Internal?)
- [ ] Who manages event-specific QR code generation (Sales? Marketing?)

---

## Supporting Research

### Competitive Analysis
**Lightspeed POS:** Offers interactive demo with sample data; no personalization; no lead capture until end
**Vend by Lightspeed:** Guided tour with video overlays; requires account creation
**Square:** Free tier allows self-exploration; no demo mode for enterprise features
**Clover:** Static demo videos only; no interactive experience

**Differentiator:** BuyerKiosk demo will be the only resale-specific demo with live simulation, concept selection, and session-scoped experimentation—combining immersion with zero commitment.

### User Research
Based on sales team feedback:
- "Customers at conferences want to 'see it live' but we can't show production data"
- "Store owners often evaluate software after hours—we lose them to competitors with self-serve demos"
- "The buying committee is usually 2-3 people; sharing a single demo experience would help"

### Market Data
- Self-service product demos increase conversion rates by 20-30% (ProductLed.com, 2024)
- 67% of B2B buyers prefer to research independently before talking to sales (Gartner)
- QR code usage increased 400% since 2020, especially at trade events (Juniper Research)