# Specification: 029-homepage-redesign-feature-showcase

## Status

| Field | Value |
|-------|-------|
| **Created** | 2026-01-13 |
| **Current Phase** | PLAN Complete - Ready for Implementation |
| **Last Updated** | 2026-01-14 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | **completed** | All sections validated, Codex reviewed |
| solution-design.md | **completed** | Codex review passed, all 5 ADRs confirmed by user |
| implementation-plan.md | **completed** | 6 phases, 182 tasks, TDD structure |

**Status values**: `pending` | `in_progress` | `completed` | `skipped`

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-01-13 | Start with comprehensive feature audit | User requested full understanding of all features before PRD |
| 2026-01-13 | Timeline: ASAP (2-3 weeks) | Fast turnaround, focus on essentials |
| 2026-01-13 | Use existing videos | Existing demo videos available, no new production needed |
| 2026-01-13 | Mobile apps: Screenshots only | Apps functional but not in app stores yet |
| 2026-01-13 | Team+ uses main demo form | Simpler conversion path, one form for all |
| 2026-01-13 | Dynamic stats via TaskEngine | Auto-update homepage stats daily from database |
| 2026-01-13 | New metrics: Stores, Years, Brands, $ Value, Uptime | More compelling than just volume metrics |
| 2026-01-13 | Hero = Integrated Platform | Value is the unified system, not individual features |
| 2026-01-13 | Analytics: PostHog | Open source with heatmaps, session recordings, feature flags |
| 2026-01-13 | Codex PRD Review | All 3 blockers resolved (measurable criteria, metrics targets, stats dependencies) |
| 2026-01-13 | SDD Architecture Pattern | Server-rendered modular template with TaskEngine cached stats |
| 2026-01-13 | SDD Analytics Decision | PostHog recommended over GA4 for heatmaps/session recording |
| 2026-01-13 | SDD Template Structure | Break 1073-line template into ~15 modular partials |
| 2026-01-14 | Codex SDD Review Complete | All 4 blockers resolved: PRD mapping, Team+ spec, stats queries, demo form alignment |
| 2026-01-14 | Should-Have Scope Clarified | Feature 8 (Video) + Feature 9 (Mobile Showcase) included; Feature 11-12 deferred |
| 2026-01-14 | ADR-1 Confirmed | Modular template partials (~15 files) approved |
| 2026-01-14 | ADR-2 Confirmed | PostHog for analytics (heatmaps, session recording) approved |
| 2026-01-14 | ADR-3 Confirmed | Daily TaskEngine cached stats approved |
| 2026-01-14 | ADR-4 Confirmed | NEW in-house demo form system to replace FormSite |
| 2026-01-14 | ADR-5 Confirmed | Single form for Homepage + Team+ page approved |
| 2026-01-14 | PLAN Created | 6-phase implementation plan with TDD structure |
| 2026-01-14 | Codex PLAN Review | 3 blockers resolved, 7 important fixes applied, ~210 tasks total |

## Context

### Initial Request
Major homepage redesign to showcase all new BuyerKiosk features and updates. Platform has evolved significantly with 28+ major feature specs delivered.

---

## 🚀 COMPREHENSIVE FEATURE INVENTORY

### Current Homepage Structure (templates/common/home.html)
~1073 lines, 13 sections to be updated/refreshed:
1. Navigation
2. Hero Section (with franchise trust logos)
3. Quick Features (4 items)
4. CTA Banner
5. Features/Benefits (3 categories)
6. Platform Components
7. Stats Section
8. Pricing Section
9. Store Showcase
10. Testimonials
11. CTA Section
12. Contact Section
13. Footer

---

## 🚀 HERO VALUE PROPOSITION (Concept/Direction)

**Core Messaging Theme**: The complete, integrated platform for resale store operations

The REAL hero is the **INTEGRATED PLATFORM** - all these systems work together seamlessly:
- Customer management flows into scheduling flows into reporting
- Events connect floor plans, staffing, promotions, and signage
- One unified system vs. cobbling together 5-6 separate software tools
- Everything works together, not in silos

*Note: Exact tagline/copy TBD during PRD - this is the strategic direction*

---

## ⭐ INTEGRATED FEATURE CATEGORIES

### 🎯 Customer Sign-In Kiosk
**Self-service check-in that eliminates paperwork**
- **Self-Service Check-In**: Customers sign in via tablet kiosk with phone/name lookup
- **Customer Queue Management**: Real-time queue visibility and management
- **Wait Time Estimates**: Automated wait time calculations
- **Customer Contact Management**: Phone, email, SMS preferences
- **SMS Notifications**: Automated "your turn" and "buy ready" messages
- **Multiple Kiosk Support**: Deploy multiple kiosks per store

### 📺 Digital Signage
**Professional in-store displays that engage customers**
- **Customizable Layouts**: Multiple screen configurations
- **Queue Display**: Show current queue position to customers
- **Promotional Content**: Display sales, events, and announcements
- **Dynamic Widgets**: Real-time data (wait times, queue count)
- **Event Integration**: Auto-display event-specific content
- **Multiple Screen Support**: Different content per display

---

### 💰 PREMIUM ADD-ON: Team+ Module ($30/month extra)
**Deserves its own homepage section + dedicated landing page**

#### Staff Scheduling System
- **Native Scheduling**: Zero-cost alternative to WhenIWork/Homebase
- **Visual Calendar**: Syncfusion EJ2 Schedule with Timeline Week, Day, Month views
- **Shift Management**: Create, edit, drag-drop, copy previous week
- **Time Clock**: Clock in/out, break tracking, timesheet approval
- **Labor Cost Tracking**: Real-time labor cost visibility during scheduling
- **Position Management**: Cashier, Buyer, Shift Lead role-based scheduling

#### AI Smart Scheduling
- **One-Click Generation**: AI fills open shifts in minutes, not hours
- **Optimization Priorities**: Labor cost, hours fairness, seniority, position coverage
- **Employee Constraints**: Respects availability, time-off, max hours, min hours
- **Role-Based Matching**: Only assigns qualified employees to appropriate shifts
- **Overtime-Aware**: Considers overtime implications automatically
- **Accept/Reject Interface**: Preview AI proposals before applying

#### Staff Chat System
- **Private Communication Hub**: Like Slack for every store location
- **Role-Based Channels**: Public channels + manager-only private channels
- **Full Messaging**: Send, edit, delete messages with audit trail
- **Image Attachments**: Share visual information (JPEG, PNG, GIF up to 10MB)
- **@Mentions**: Tag team members with push notifications
- **Emoji Reactions**: Quick acknowledgments without typing
- **Read Receipts**: Know who has seen messages
- **Task Integration**: Workbook tasks/notes appear as system messages

#### BuyerKiosk Team Mobile App (Employee App)
- **Schedule at Your Fingertips**: View upcoming shifts from phone
- **Geofenced Clock-In**: Clock in from parking lot (within store radius)
- **Break Tracking**: Log paid/unpaid breaks
- **Push Notifications**: Schedule changes, shift reminders, team messages
- **Performance Dashboard**: Daily stats (buys completed, items processed)
- **Time-Off Requests**: Submit requests from phone
- **Shift Swaps**: Request swaps with coworkers
- **Availability Management**: Set recurring availability
- **Multi-Store Support**: Works for employees at multiple locations

#### BuyerKiosk Live Mobile App (Manager App)
- **Mobile Command Center**: Store metrics + scheduling in one app
- **Instant Approvals**: Approve/deny shift swaps, time-off, overrides
- **Complete Visibility**: Who's working, labor costs, your own schedule
- **Manager Dashboard**: Scheduled vs clocked in, late, absent, pending requests
- **Shift Management**: Create open shifts, extend shifts, cover gaps
- **Multi-Store Efficiency**: Switch between stores seamlessly
- **Biometric Auth**: Face ID/Touch ID for quick access

---

### 📊 DAYBOOK (Centralized Operations Hub)
**The command center for day-to-day operations**
- **Unified Workspace**: Everything staff needs in one place
- **Buy Queue Management**: Real-time queue visibility
- **Schedule Panel**: Who's working today, clock-in status
- **Notes Feed**: Team communication and shift handoffs
- **Task Lists**: Actionable to-do items for staff
- **KPI Bar**: Daily performance metrics at a glance
- **Whiteboard Panel**: Digital store whiteboard
- **Backstock Summary**: Inventory visibility
- **Floor Plan Panel**: Visual store layout reference
- **Customer Chat**: Two-way SMS conversations

---

### 📈 NEW REPORTING & ANALYTICS
**Data-driven decision making for resale stores**

#### Inventory Velocity Dashboard
- Days-to-sale analysis by velocity bucket
- Margin erosion tracking (items 180+ days = 55% margin loss)
- Period-over-period comparison

#### Category Momentum Heat Map
- MACD-style momentum indicators
- Trend detection before patterns establish
- Bullish/bearish crossover alerts

#### Enhanced P&L Dashboard
- Year-over-year comparison
- Variance highlighting vs goals
- Seasonal pattern analysis

#### Seller Analytics
- Retention patterns
- Cohort behavior analysis
- Wait time correlation with satisfaction

---

### 🗺️ FLOOR PLAN TOOL (Syncfusion Designer)
**Professional floor planning for retail optimization**
- **Visual Designer**: Drag-drop rack placement with snap-to-grid
- **Symbol Palette**: 12 fixture types (rounders, gondolas, wall units, etc.)
- **Category Assignment**: Map merchandise to rack sockets
- **Sales Heatmap**: Visualize revenue by floor area (gradient + socket coloring)
- **Maintenance Tracking**: Prioritized rack maintenance with audit trails
- **Layout Versioning**: Plan seasonal/event floor changes
- **Auto-Generated Move Tasks**: System creates tasks for layout transitions
- **Scheduled Activation**: Layouts auto-activate on planned dates

---

### 💬 TWO-WAY CUSTOMER SMS CHAT
**Transform one-way notifications into conversations**
- **Chat Panel in Workbook**: See and respond to customer messages
- **Smart Routing**: Inbound SMS routes to correct store by purchase history
- **Canned Messages**: Pre-approved templates for initial contact
- **Freetext After Reply**: Natural conversation once customer responds
- **Delivery Status**: See if messages were delivered
- **Template Management**: Admin creates/edits message templates
- **TCPA Compliance**: Granular opt-out handling
- **Usage Tracking**: Billable interactive vs free transactional messages

---

### 🎪 UNIFIED EVENT MANAGEMENT
**Complete event lifecycle management**
- **Event Calendar**: Plan store events, promotions, seasonal changes
- **Multi-System Integration**: Events connect to:
  - Floor plan layouts (auto-activate)
  - Scheduling (staffing requirements)
  - Promotions (Comeback Cash campaigns)
  - Digital signage
- **Task Generation**: Auto-create prep tasks for events

---

### 💵 COMEBACK CASH (Promotional Coupons)
**"Kohl's Cash" style loyalty programs**
- **Flexible Campaigns**: Sales-side and buy-side programs
- **Tiered Earning**: Spend $X, earn $Y
- **Time-Boxed Events**: Automatic start/end dates
- **SMS Reminders**: Notify customers when coupons become redeemable
- **POS Integration**: Real-time settings sync via Ably
- **Redemption Tracking**: Track generation and redemption rates
- **Double-Up Options**: Higher rewards for bigger transactions

---

### 📦 BACKSTOCK INVENTORY MANAGEMENT
**Complete inventory tracking for resale stores**
- **Bin Management**: Track storage bins with UUID labels, categories, locations
- **Aging System**: Visual aging indicators (green → yellow → red) to identify stale inventory
- **Category & Location Tracking**: Organize bins by merchandise type and storage area
- **Action Logging**: Complete accountability trail for all bin changes
- **Events & Scheduling**: Schedule audits, rotations, and sales events
- **Reports Dashboard**:
  - Summary stats (total bins, average age)
  - Age distribution charts
  - Category health scores
  - Location utilization
  - Stale inventory alerts
  - Activity summaries

---

### 📒 QuickBooks Integration
**Automated accounting that saves hours**
- Automated journal entry sync
- Financial data integration
- Seamless accounting workflow
- No manual data entry

### ⭐ FiveStars Loyalty Integration
**Native loyalty program support**
- Points calculation and reward redemption
- Customer rewards management
- Seamless POS integration

---

### 📱 MOBILE ECOSYSTEM

| App | Audience | Key Features |
|-----|----------|--------------|
| **BuyerKiosk Team** | Employees | Schedule viewing, geo-fenced clock-in, break tracking, performance stats, notifications |
| **BuyerKiosk Live** | Managers/Owners | Store metrics, scheduling approvals, labor visibility, shift management |

---

## SCOPE FOR HOMEPAGE REDESIGN

### Homepage Updates
1. **Refresh all existing sections** with current messaging and capabilities
2. **Add dedicated Team+ section** showcasing premium scheduling/chat module
3. **Update feature highlights** with Daybook, Floor Plan, Reporting, Chat
4. **Refresh stats section** with current numbers
5. **Update pricing** to show Team+ addon pricing

### New Landing Page: Team+ Module
- Dedicated page for premium scheduling features
- Comparison to competitors (WhenIWork, Homebase)
- Feature breakdown with visuals
- Pricing details ($30/month)
- Mobile app showcase (Team + Live apps)

### Design Goals
- **Compelling**: Make the software feel premium and modern
- **Conversion-focused**: Clear CTAs for demo scheduling
- **Feature-rich but organized**: Don't overwhelm, but showcase depth
- **Mobile-responsive**: Works on all devices

---
*This file is managed by the specification-management skill.*