# Specification: 020-digital-signage-widgets

## Status

| Field | Value |
|-------|-------|
| **Created** | 2025-12-19 |
| **Current Phase** | PLAN Complete - Ready for Implementation |
| **Last Updated** | 2025-12-19 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | Comprehensive PRD with 23 features, 4 personas, detailed specs |
| solution-design.md | completed | Full architecture with 7 confirmed ADRs, Alpine.js player, hybrid layouts |
| implementation-plan.md | completed | 6 phases, 210 tasks, 15 parallel groups, TDD structure |

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

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2025-12-19 | Template-based layouts (not drag-drop) | Simpler UX, faster to implement, easier for store managers |
| 2025-12-19 | Landscape 16:9 only | Simplifies design, covers majority of use cases |
| 2025-12-19 | Offline-first architecture | Critical for store reliability during internet outages |
| 2025-12-19 | Store-level social approval | Brand safety controlled by each store manager |
| 2025-12-19 | Canva Connect integration | Enables professional designs without leaving platform |
| 2025-12-19 | Named display zones | Supports multiple displays with different content per store |
| 2025-12-19 | Simple sequential playlists | Avoids complexity of time-based scheduling rules |
| 2025-12-19 | Full QR attribution tracking | Measures ROI of in-store signage |
| 2025-12-19 | Auto-migrate existing slides | Zero disruption for stores during upgrade |
| 2025-12-19 | Deferred live display preview | Complexity vs value tradeoff, can add later |
| 2025-12-19 | **ADR-1**: Widget Registry Pattern | Extensible widget system without core code changes |
| 2025-12-19 | **ADR-2**: Service Worker for Offline | Modern browser standard for cache control |
| 2025-12-19 | **ADR-3**: JSON Widget Config | Flexible schema, no migrations for new settings |
| 2025-12-19 | **ADR-4**: Hybrid Layout System | Templates + adjustable zones (modified from PRD) |
| 2025-12-19 | **ADR-5**: Redis for External Caching | Already in stack, TTL support |
| 2025-12-19 | **ADR-6**: Alpine.js for Display Player | Lightweight reactivity (15KB), better than vanilla JS |
| 2025-12-19 | **ADR-7**: Additive Schema Changes | Preserves legacy system, gradual migration |
| 2025-12-19 | **PLAN**: 6-phase implementation | Foundation → Widgets → Display Player → External → Admin UI → Integration |
| 2025-12-19 | **PLAN**: 210 tasks total | TDD structure: Prime → Test → Implement → Validate per phase |
| 2025-12-19 | **PLAN**: 15 parallel groups | Widget implementations, API controllers, and integrations can parallelize |

## Context

### User Request
Refactor the digital signage platform to support:
1. **Widget-based layouts** - Multiple widgets per page with customizable layouts
2. **Page types** - Full-screen (legacy) + multi-widget layouts
3. **New widget types**: Social Media, Weather, Queue widgets, QR codes, Events, Custom text
4. **New integrations**: Canva, Facebook/Instagram/TikTok, Weather API

### Existing Platform Analysis
The current platform has:
- Slide-based loop system (dsSlides, dsLoop, corpSlides, hbSlides)
- Image/Video/Queue slide types
- Scheduling with start/expire dates
- Event management integration
- Tagging system for slide categorization
- Multi-store architecture (store + corporate + Hipbone sources)
- Display player using jQuery Cycle2 + Video.js
- Real-time queue display updates every 4 seconds

### Key Transformation
From: Linear slide loop (one slide at a time)
To: Page-based system with layouts supporting multiple widgets per page

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