# 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 website into a compelling showcase that clearly communicates the value of an integrated resale store operations platform, driving demo requests and customer acquisition while introducing the premium Team+ module.

### Problem Statement
BuyerKiosk's current homepage (~1073 lines, 13 sections) was built before significant platform expansion. The website now fails to communicate:

1. **Platform evolution**: 28+ major features have been delivered (scheduling, AI, floor plans, chat, reporting, mobile apps) but aren't showcased
2. **Integration value**: The core differentiator - that all systems work together seamlessly - isn't effectively communicated
3. **Premium offering**: The Team+ module ($30/month) with scheduling, AI, staff chat, and mobile apps has no dedicated presence
4. **Modern capabilities**: Features like AI scheduling, two-way customer chat, and inventory analytics aren't visible to prospects

**Consequences of not solving:**
- Lost leads who don't see BuyerKiosk as a complete solution
- Difficulty justifying premium pricing without showcasing full value
- Team+ module underperforms due to lack of visibility
- Prospects choose competitors with better-presented (but inferior) feature sets

### Value Proposition
A redesigned website that:
- **Communicates integration**: Shows prospects that BuyerKiosk replaces 5-6 separate software tools with one unified platform
- **Showcases modern features**: Highlights AI scheduling, floor plan heatmaps, two-way chat, and other differentiators
- **Drives conversions**: Clear CTAs and compelling messaging that generates demo requests
- **Introduces Team+**: Dedicated section and landing page for premium scheduling/chat module
- **Builds trust**: Updated stats, testimonials, and social proof

## User Personas

### Primary Persona: Prospective Store Owner (Rachel)
- **Demographics:** 30-55 years old, owns or is opening a resale/consignment store (Plato's Closet, Clothes Mentor, etc.), moderate technical expertise, evaluating software solutions
- **Goals:**
  - Find software that handles customer check-in and queue management
  - Reduce the number of separate software tools needed to run the store
  - Understand total cost of ownership before committing
  - See social proof from similar stores
- **Pain Points:**
  - Overwhelmed by evaluating multiple software vendors for different needs
  - Unclear which features are included vs. extra cost
  - Hard to tell if software is designed for resale/consignment specifically
  - Websites that are vague about capabilities and pricing

### Secondary Persona: Existing Customer Evaluating Team+ (Marcus)
- **Demographics:** 35-50 years old, current BuyerKiosk customer, considering upgrading to premium features
- **Goals:**
  - Understand what Team+ offers beyond current subscription
  - Evaluate if $30/month is worth replacing current scheduling tool (WhenIWork, Homebase)
  - See how Team app and Live app work for their employees and managers
- **Pain Points:**
  - Paying for multiple software subscriptions that don't integrate
  - No single place to see what Team+ includes and how it works
  - Uncertainty about whether AI scheduling actually saves time

### Tertiary Persona: Franchise Owner/Regional Manager (David)
- **Demographics:** 40-60 years old, owns or manages 3-10 resale stores, focuses on efficiency and standardization
- **Goals:**
  - Find a platform that works across multiple locations
  - Standardize operations without micromanaging each store
  - Get visibility into store performance from anywhere
- **Pain Points:**
  - Each store uses different tools, creating inconsistency
  - No centralized view of operations across stores
  - Hard to compare store performance

## User Journey Maps

### Primary User Journey: Prospect Discovery and Evaluation
1. **Awareness:** Rachel searches for "resale store software" or "consignment store check-in system" and finds BuyerKiosk via search/referral
2. **Consideration:** Lands on homepage, quickly scans to understand what BuyerKiosk does and if it's relevant to her business
3. **Exploration:** Scrolls through feature sections, looks for specific capabilities (queue management, scheduling, reporting)
4. **Validation:** Looks for social proof (store logos, testimonials, stats) to confirm legitimacy
5. **Action:** Clicks "Schedule Demo" or "Contact Us" to learn more
6. **Follow-up:** May return to review pricing or specific features before/after demo

### Secondary User Journey: Existing Customer Team+ Evaluation
1. **Trigger:** Marcus sees mention of Team+ in the app or receives marketing email
2. **Discovery:** Visits Team+ landing page (or homepage section) to understand the offering
3. **Evaluation:** Reviews feature list, compares to current WhenIWork subscription
4. **Calculation:** Considers $30/month vs. current scheduling costs + added benefits
5. **Decision:** Either signs up for Team+ trial or requests more information

### Tertiary User Journey: Multi-Store Evaluation
1. **Trigger:** David hears about BuyerKiosk from another franchise owner or corporate recommendation
2. **Research:** Visits homepage looking for multi-store capabilities
3. **Deep Dive:** Looks for features like centralized reporting, mobile management, cross-store visibility
4. **Validation:** Looks for franchise logos and case studies
5. **Contact:** Reaches out for enterprise/multi-store demo

## Feature Requirements

### Must Have Features (Homepage)

#### Feature 1: Integrated Platform Hero Section
- **User Story:** As a prospect, I want to identify BuyerKiosk's core value proposition within 5 seconds of landing so that I can decide if it's relevant to my business
- **Acceptance Criteria:**
  - [ ] Headline (max 10 words) communicates "integrated platform for resale stores"
  - [ ] Subhead (max 25 words) explains resale/consignment store focus
  - [ ] Primary CTA "Schedule Demo" button visible above the fold at 1024x768 and 375x812
  - [ ] Secondary CTA (Watch Video or Learn More) positioned below primary CTA
  - [ ] At least 3 franchise/brand logos visible in hero area
  - [ ] Hero section renders correctly at breakpoints: 375px, 768px, 1024px, 1440px
  - [ ] PostHog event `hero_cta_clicked` fires on primary CTA click with `cta_type` property
  - [ ] Page loads with LCP < 2.5s on 4G connection

#### Feature 2: Feature Showcase Sections
- **User Story:** As a prospect, I want to scan all major features within 60 seconds of scrolling so that I can understand the full platform capabilities
- **Acceptance Criteria:**
  - [ ] 11 feature sections displayed: Sign-In Kiosk, Digital Signage, Daybook, Backstock, Floor Plan, Customer Chat, Reporting, Events, Comeback Cash, QuickBooks, FiveStars
  - [ ] Each section follows consistent structure: headline (max 6 words), description (max 50 words), 3-4 bullet points, visual/screenshot
  - [ ] Each section has unique CSS class for PostHog heatmap tracking (e.g., `data-posthog-section="kiosk"`)
  - [ ] PostHog event `section_viewed` fires when section enters viewport (via Intersection Observer)
  - [ ] All section visuals lazy-load to maintain LCP < 2.5s
  - [ ] Sections render in single column on mobile (< 768px), two-column grid on desktop

#### Feature 3: Team+ Premium Section
- **User Story:** As a prospect or existing customer, I want to identify Team+ pricing and key benefits within 10 seconds so that I can evaluate if it's worth the additional cost
- **Acceptance Criteria:**
  - [ ] Section visually distinct from core features (different background color or border)
  - [ ] Price "$30/month per store" displayed prominently (font-size >= 1.25rem)
  - [ ] "Premium Add-On" or "Optional Upgrade" badge clearly visible
  - [ ] 5 feature bullets: Scheduling, AI Smart Scheduling, Staff Chat, Team App, Live App
  - [ ] "Learn More" CTA links to `/team-plus` landing page
  - [ ] PostHog event `team_plus_cta_clicked` fires on CTA click
  - [ ] Section includes at least one visual (screenshot or illustration)

#### Feature 4: Social Proof & Stats Section
- **User Story:** As a prospect, I want to verify BuyerKiosk's credibility within 5 seconds so that I feel confident in my evaluation
- **Acceptance Criteria:**
  - [ ] 6 dynamic stats displayed in grid layout (2x3 on mobile, 6x1 on desktop):
    - [ ] Stores Served: `SELECT COUNT(*) FROM kiosk_buykiosk.stores WHERE active = 1`
    - [ ] Years in Business: Static "10+ Years" (founded 2015)
    - [ ] Franchise Brands: `SELECT COUNT(DISTINCT concept) FROM kiosk_buykiosk.stores WHERE active = 1`
    - [ ] Dollar Value Processed: `SELECT SUM(buyTotal) FROM all store buyQueue tables` (formatted as "$XXM+")
    - [ ] Buys Processed: `SELECT SUM(buyCount) FROM kiosk_buykiosk.stores` (formatted as "XXM+")
    - [ ] Uptime: Static "99.9%" (based on historical uptime)
  - [ ] **Data Pipeline**: TaskEngine job `HomepageStatsJob` runs daily at 2am, writes to `kiosk_buykiosk.homepage_stats` cache table
  - [ ] **Fallback Behavior**: If cache table empty/stale (>48hrs), display last known values with no error to user
  - [ ] At least 6 franchise/brand logos displayed (Plato's Closet, Clothes Mentor, etc.)
  - [ ] 2-3 customer testimonials with: quote, name, store name, store type
  - [ ] Stats numbers animate on scroll into view (count-up effect)
  - [ ] PostHog event `stats_section_viewed` fires when section enters viewport

#### Feature 5: Pricing Section
- **User Story:** As a prospect, I want to find pricing information within 2 clicks so that I can budget appropriately
- **Acceptance Criteria:**
  - [ ] Pricing displayed by store type: Phone Check-In, Apparel Brands, Sports & Gear (existing tiers)
  - [ ] Team+ add-on pricing: "$30/month per store" clearly marked as "optional"
  - [ ] Each tier shows: price, included features (3-5 bullets), CTA
  - [ ] "Contact for custom pricing" option for enterprise/multi-store
  - [ ] PostHog event `pricing_section_viewed` fires when section enters viewport
  - [ ] PostHog event `pricing_cta_clicked` fires with `tier` property on CTA click

#### Feature 6: Primary CTA (Schedule Demo)
- **User Story:** As a prospect ready to learn more, I want to request a demo in under 60 seconds so that I can see the platform in action
- **Acceptance Criteria:**
  - [ ] Demo CTA button appears: hero section, after feature sections (mid-page), footer
  - [ ] CTA button text: "Schedule Demo" (consistent across all placements)
  - [ ] Form fields (all required): name, email, phone, store name, store type (dropdown)
  - [ ] Store type dropdown options: Resale/Consignment, Sporting Goods, Phone Check-In, Other
  - [ ] Form validation: email format, phone format (10+ digits), all fields non-empty
  - [ ] On submit: POST to existing demo request endpoint, show "Thank you" confirmation
  - [ ] PostHog events: `demo_form_opened`, `demo_form_submitted` with `store_type` property
  - [ ] Form error state: inline validation messages, no page reload on error

### Must Have Features (Team+ Landing Page)

#### Feature 7: Dedicated Team+ Landing Page
- **User Story:** As a prospect or customer interested in scheduling, I want to compare Team+ to alternatives within 2 minutes so that I can make an informed decision
- **Acceptance Criteria:**
  - [ ] Route: `/team-plus` (new page)
  - [ ] Accessible from: main navigation "Team+" link, homepage Team+ section CTA
  - [ ] Hero section: headline (max 8 words), subhead explaining "replace WhenIWork/Homebase"
  - [ ] 5 feature sections with screenshots:
    - [ ] Staff Scheduling: calendar screenshot, shift management, time clock
    - [ ] AI Smart Scheduling: one-click generation screenshot, "saves 2-4 hours/week"
    - [ ] Staff Chat: channels screenshot, @mentions, notifications
    - [ ] Team App: device mockup with 3 key screens (schedule, clock-in, chat)
    - [ ] Live App: device mockup with 3 key screens (dashboard, approvals, schedule)
  - [ ] Pricing: "$30/month per store" with breakdown of what's included
  - [ ] Competitor comparison table: Team+ vs WhenIWork vs Homebase (features, price)
  - [ ] CTA: "Schedule Demo" (uses main demo form, pre-selects "Team+ interest")
  - [ ] Mobile app screenshots only (no app store badges - apps not published)
  - [ ] PostHog events: `team_plus_page_view`, `team_plus_demo_requested`
  - [ ] Page loads with LCP < 2.5s

### Should Have Features

#### Feature 8: Interactive Feature Demo/Video
- **User Story:** As a prospect, I want to see the software in action so that I can understand the user experience
- **Acceptance Criteria:**
  - [ ] Product demo video on homepage
  - [ ] Feature-specific videos/GIFs in relevant sections
  - [ ] Interactive demo option if feasible

#### Feature 9: Mobile App Showcase
- **User Story:** As a prospect, I want to see the mobile apps so that I understand the mobile experience
- **Acceptance Criteria:**
  - [ ] Screenshots of Team app and Live app
  - [ ] Feature highlights for each app
  - [ ] No app store badges (apps not yet published) - use "Coming Soon" or device mockups only

#### Feature 10: Updated Navigation
- **User Story:** As a visitor, I want clear navigation so that I can find specific information easily
- **Acceptance Criteria:**
  - [ ] Navigation includes: Features, Team+, Pricing, Contact
  - [ ] Mobile-responsive hamburger menu
  - [ ] Login link for existing customers

### Could Have Features

#### Feature 11: Case Studies Section
- **User Story:** As a prospect, I want to read detailed success stories so that I can relate to similar stores
- **Acceptance Criteria:**
  - [ ] 2-3 detailed case studies from different store types
  - [ ] Metrics and outcomes highlighted
  - [ ] Quotes from store owners

#### Feature 12: Resource Center Link
- **User Story:** As a prospect doing research, I want access to educational content so that I can learn more about resale store operations
- **Acceptance Criteria:**
  - [ ] Link to blog/resources if available
  - [ ] Integration guides for QuickBooks, FiveStars

### Won't Have (This Phase)

1. **Self-service signup**: No online signup/checkout flow - demo-based sales process continues
2. **Customer portal/login from homepage**: Existing login flow remains unchanged
3. **Blog/Content marketing section**: Not in scope for this redesign
4. **Multi-language support**: English only
5. **Live chat widget**: Not adding live chat to homepage
6. **Detailed API documentation**: Technical docs remain separate

## Detailed Feature Specifications

### Feature: Team+ Premium Section (Homepage)
**Description:** A dedicated section on the homepage that introduces the Team+ premium add-on, highlighting its value as a replacement for third-party scheduling tools.

**Content Structure:**
1. Section header: TBD during design phase (e.g., "Supercharge Your Team" or "The Complete Team Management Solution")
2. Price callout: "+$30/month per store"
3. Feature grid or list:
   - Staff Scheduling with visual calendar
   - AI Smart Scheduling (saves 2-4 hours/week)
   - Staff Chat for team communication
   - BuyerKiosk Team app for employees
   - BuyerKiosk Live app for managers
4. Visual: Screenshot or illustration of scheduling interface
5. CTA: "Learn More" linking to dedicated Team+ page

**Business Rules:**
- Rule 1: Section should clearly indicate this is an add-on (not included in base price)
- Rule 2: Value proposition should focus on replacing WhenIWork/Homebase (cost savings + integration)
- Rule 3: AI scheduling should be highlighted as a unique differentiator
- Rule 4: Mobile apps should be mentioned but detailed on landing page

**Edge Cases:**
- Scenario 1: User clicks CTA before Team+ page exists → Expected: Links to contact form with Team+ pre-selected
- Scenario 2: User is existing customer already paying for Team+ → Expected: Section still relevant for validation
- Scenario 3: Demo form submission fails (network error) → Expected: Show "Something went wrong, please try again" message, retain form data
- Scenario 4: Demo form validation fails → Expected: Inline error messages per field, no form clear, focus on first error field
- Scenario 5: Stats cache table is empty/stale (>48hrs) → Expected: Display last cached values, no error shown to user
- Scenario 6: Stats cache table missing entirely → Expected: Display hardcoded fallback values (current homepage values)
- Scenario 7: User on slow connection (3G) → Expected: Images lazy-load, page remains usable, skeleton loaders for dynamic content
- Scenario 8: User has JavaScript disabled → Expected: Static content visible, forms work via standard POST, no animations
- Scenario 9: Video fails to load → Expected: Show poster image, hide play button, no broken player UI
- Scenario 10: Mobile user in landscape mode → Expected: Layout adapts, no horizontal scroll, CTAs remain accessible

## Success Metrics

### Key Performance Indicators

| KPI | Baseline | Target | Timeframe |
|-----|----------|--------|-----------|
| **Demo Conversion Rate** | TBD (measure week before launch via PostHog) | +25% improvement | 60 days post-launch |
| **Bounce Rate** | TBD (measure via PostHog) | -15% reduction | 60 days post-launch |
| **Avg. Time on Page** | TBD (measure via PostHog) | +30% increase | 60 days post-launch |
| **Scroll Depth** | TBD (measure via PostHog heatmaps) | 70% reach pricing section | 60 days post-launch |
| **Team+ Page CTR** | N/A (new page) | 5% of homepage visitors | 60 days post-launch |
| **Mobile Engagement** | TBD | Equal to desktop (bounce, time on page) | 60 days post-launch |
| **Core Web Vitals** | TBD | LCP < 2.5s, CLS < 0.1, FID < 100ms | Launch day |

**Baseline Measurement Plan**: Install PostHog 1 week before launch to establish baselines on current homepage.

### Analytics Platform

**PostHog** (open source) - Self-hosted or PostHog Cloud
- Event tracking for all user interactions
- Heatmaps for click/scroll analysis
- Session recordings for UX debugging
- Feature flags for A/B testing (future)

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `$pageview` | path, referrer, device, utm_* | Track traffic sources (auto-captured) |
| `section_viewed` | section_name, time_visible | Track feature section engagement |
| `hero_cta_clicked` | cta_type, position | Track hero conversion intent |
| `team_plus_cta_clicked` | source (homepage/nav) | Track Team+ interest |
| `pricing_section_viewed` | - | Track pricing engagement |
| `pricing_cta_clicked` | tier | Track pricing conversion intent |
| `demo_form_opened` | source | Track form engagement |
| `demo_form_submitted` | store_type, source | Track conversions |
| `demo_form_error` | field, error_type | Track form friction |
| `team_plus_page_view` | source (homepage/direct/nav) | Track Team+ landing page |
| `video_played` | video_name, watch_percent | Track video engagement |
| `stats_section_viewed` | - | Track social proof engagement |

---

## Constraints and Assumptions

### Constraints
- **Platform:** Must work within existing Twig/Slim template system
- **Design System:** Should use existing CSS design system (Bootstrap 5, tokens.css)
- **Content:** Requires copywriting for headlines, descriptions, CTAs (owner to provide/approve)
- **Assets:** Existing videos available; new screenshots needed for: Daybook, Floor Plan, Team+, mobile apps
- **Timeline:** ASAP - 2-3 week target (focus on essentials, fast turnaround)
- **SEO:** IN SCOPE - Maintain existing URL structure, proper meta tags, semantic HTML, Open Graph tags
- **Accessibility:** IN SCOPE - WCAG 2.1 Level AA compliance (alt text, keyboard nav, color contrast, focus states)
- **Performance:** IN SCOPE - Core Web Vitals targets (LCP < 2.5s, CLS < 0.1, FID < 100ms)
- **Browser Support:** Chrome, Safari, Firefox, Edge (latest 2 versions); IE11 NOT supported

### Assumptions
- Existing home.html template will be redesigned in place (not new URL)
- Team+ landing page will be a new page/route
- Current login flow and authenticated areas remain unchanged
- Demo request process/CRM remains unchanged
- Mobile apps (Team, Live) are functional but not published to app stores yet - use screenshots only (no app store badges)

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Content/copy delays | High | Medium | Start copywriting early; use placeholder content for design |
| Missing screenshots/assets | Medium | Medium | Create asset list early; prioritize hero and key sections |
| Scope creep from feature additions | Medium | High | Strict MoSCoW adherence; defer nice-to-haves |
| Mobile responsiveness issues | Medium | Low | Test on multiple devices throughout development |
| SEO impact from restructure | Medium | Low | Maintain key URLs; implement redirects if needed |

## Open Questions

- [x] ~~What is the target launch date for this redesign?~~ → **ASAP (2-3 weeks)**
- [x] ~~What video/demo assets are available or need to be created?~~ → **Existing videos available**
- [x] ~~Are the mobile apps (Team, Live) ready to be showcased with app store badges?~~ → **Screenshots only (apps not in stores yet)**
- [x] ~~Should the Team+ landing page have a separate demo form or use the main one?~~ → **Same form (main demo form)**
- [x] ~~Are there specific competitor websites to reference for design inspiration?~~ → **No specific reference - use best judgment**
- [x] ~~What are the current stats to display?~~ → **Dynamic stats via TaskEngine: Stores served, Years in business, Franchise brands, $ processed, Buys processed, Uptime**
- [ ] What are the current homepage analytics (traffic, bounce rate, conversion)? *(Nice to have for baseline, not blocking)*

---

## Supporting Research

### Competitive Analysis
No specific competitor websites required for reference. Design approach will follow modern SaaS best practices with clean feature presentation, clear CTAs, and mobile-responsive layouts.

**Industry context** (resale/consignment software):
- SimpleConsign, ConsignPro, Ricochet - direct competitors
- Toast, Square - design inspiration for clean SaaS presentation

### User Research
Based on existing customer feedback:
- Store owners want to understand "what's included" quickly
- Integration/unified platform is a key selling point
- Video demos are highly requested during sales process
- Pricing transparency is valued

### Market Data
- US secondhand apparel market: $43B+ (ThredUp Resale Report)
- Growing demand for integrated retail management solutions
- Shift from multiple point solutions to unified platforms
- Mobile-first management expectations increasing

---

*PRD Status: COMPLETE - Codex reviewed, all blockers resolved, ready for SDD*
*Review Date: 2026-01-13*