# Specification: 021-demo-dashboard

## Status

| Field | Value |
|-------|-------|
| **Created** | 2025-12-19 |
| **Current Phase** | Implementation Plan Complete |
| **Last Updated** | 2025-12-19 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | Full PRD with 13 features, validation checklist passed |
| solution-design.md | completed | Architecture with 5 ADRs approved, shadow table pattern |
| implementation-plan.md | completed | 121 tasks across 5 phases, TDD structure, all validation checks passed |

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

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2025-12-19 | Separate subdomain + server for isolation | Maximum security - no production data leakage risk |
| 2025-12-19 | Same codebase, separate config | Easier to maintain, prevents code drift |
| 2025-12-19 | Shadow tables for session-scoped writes | Best balance: allows user experimentation while simulation runs continuously |
| 2025-12-19 | Magic link via QR code access | Minimal friction + lead capture (email required) |
| 2025-12-19 | 24-hour session duration | Good for conference follow-up without indefinite resource use |
| 2025-12-19 | User chooses store concept on entry | Personalized experience for different franchises |
| 2025-12-19 | Flows.sh for interactive tour | Commercial quality, WYSIWYG editor, wait/branch steps |
| 2025-12-19 | Full funnel analytics | Marketing ROI measurement required |
| 2025-12-19 | Static + dynamic QR codes | General use + event-specific tracking |
| 2025-12-19 | Continuous simulation via TaskEngine | Demo always feels "alive" with realistic activity |

## Key Architecture Highlights

### Data Isolation Strategy
- **Subdomain:** demo.buyerkiosk.com
- **Database:** Completely separate demo database (not connected to production)
- **Codebase:** Same repo, environment flags differentiate behavior

### User Experience Model
1. User scans QR → enters email → receives magic link
2. Clicks link → selects store concept (pc/ou/se)
3. Enters demo → optional guided tour launches
4. Explores freely → makes changes (isolated to their session)
5. Session expires in 24 hours → all user changes discarded

### Simulation Model
- MockDataGenerator runs continuously on demo environment
- Writes to "baseline" demo tables
- User writes go to session-scoped shadow tables
- Reads merge baseline + shadow for personalized view

## MVP Feature Scope

### Must Have (8 features)
1. Secure demo environment (isolated subdomain)
2. Magic link access
3. Store concept selection
4. Continuous live simulation
5. Session-scoped user actions (shadow tables)
6. Interactive guided tour (Flows.sh)
7. QR code generation (static + dynamic)
8. Lead capture & CTAs

### Should Have (2 features)
9. Full funnel analytics
10. Demo environment dashboard

### Could Have (3 features)
11. Personalized demo paths
12. Comparison mode
13. Video walkthroughs

## Success Metrics
- 100+ demo sessions/month within 3 months
- 10+ min average session duration
- 40%+ tour section completion
- 15%+ conversion to sales contact
- 10% increase in conference-sourced leads

## Open Questions (Remaining)
- [ ] Email service for magic links
- [ ] Analytics platform choice
- [ ] Calendar scheduling integration
- [ ] QR code generation ownership (Sales/Marketing)

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