# Digital Signage System Overview

> **Last Updated**: December 2025
> **Status**: Production
> **Version**: 1.0

## Executive Summary

The Digital Signage System is a subsystem within BuyerKiosk that manages content loops (playlists) for in-store display screens. It enables stores to show rotating slides (images, videos, and live queue information) on customer-facing displays.

## System Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    DIGITAL SIGNAGE SYSTEM                       │
└─────────────────────────────────────────────────────────────────┘

ADMIN PANEL ──→ Controllers ──→ Models ──→ Databases
     │              │                         │
     │         UploadController          ┌────┴────┐
     │         LoopController            │  Store  │ (dsSlides, dsLoop)
     │         SlideController           │   DB    │
     │         SlideScheduleController   └────┬────┘
     │              │                         │
     │              ↓                    ┌────┴────┐
     │         Ably Push ──────────→    │ Global  │ (corpSlides, hbSlides,
     │              │                   │   DB    │  digitalSignSchedule)
     │              ↓                   └─────────┘
     │         DISPLAY DEVICES
     │         (loop.html + JS)
     │              │
     └──→ Queue Integration (type 3 slides)
              │
              ↓
         Service Queue APIs
```

## Key Capabilities

| Feature | Description |
|---------|-------------|
| **Multi-Source Slides** | Support for store-specific, corporate, and partner slides |
| **Media Types** | Images (gif, jpg, png) and videos (mp4, webm) |
| **Scheduling** | Time-based activation and expiration of slides |
| **Real-time Updates** | Ably messaging for instant schedule changes |
| **Queue Display** | Live integration with service queue |
| **Video Processing** | FFMpeg-based thumbnail extraction and duration detection |
| **Offline Sync** | Desktop sync app for disconnected displays |

## Technology Stack

| Component | Technology |
|-----------|------------|
| Backend | PHP 8.x with Slim 2.6.2 |
| Templates | Twig 1.44.8 |
| Database | MySQL (multi-store pattern) |
| Real-time | Ably messaging |
| Video Processing | FFMpeg/FFProbe |
| Frontend Animations | jQuery Cycle2 + Animate.css |
| Timezone Handling | Moment.js |

## Directory Structure

```
userfrosting/
├── src/BuyerKiosk/DigitalSign/
│   ├── Slide.php                    # Store slide entity
│   ├── CorpSlide.php                # Corporate slide entity
│   ├── LoopItem.php                 # Loop entry entity
│   ├── StoreLoop.php                # Playlist management
│   ├── AvailableSlides.php          # Slide aggregator
│   ├── UploadHandler.php            # File upload with FFMpeg
│   └── Controllers/
│       ├── LoopController.php       # Loop/playlist management
│       ├── SlideController.php      # Store slide CRUD
│       ├── UploadController.php     # Media uploads
│       ├── CorpUploadController.php # Corporate uploads
│       └── SlideScheduleController.php # Schedule processing
├── routes/groups/
│   └── digitalsign.php              # Route definitions
└── templates/themes/default/ds/
    ├── loop.html                    # Main display template
    ├── manage-loop.html             # Admin: Loop management
    ├── manage-slides.html           # Admin: Slide library
    ├── add-slide.html               # Admin: Add slide form
    ├── add-media.html               # Admin: Upload form
    └── snips/
        ├── img.html                 # Image slide component
        ├── vid.html                 # Video slide component
        └── queue.html               # Queue display component

public_html/
└── upload/digitalSign/
    ├── corp/                        # Corporate slides
    ├── {typeNum}/                   # Store-specific slides
    └── thumbs/                      # Thumbnails
```

## Related Documentation

- [Business Rules](./digital-signage-business-rules.md) - Detailed business logic and rules
- [Technical Patterns](./digital-signage-technical-patterns.md) - Architecture and code patterns
- [Integration Map](./digital-signage-integrations.md) - API and service connections
- [Recommendations](./digital-signage-recommendations.md) - Improvement roadmap

## Quick Reference

### API Endpoints

| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/:typeNum/upload` | Upload media file |
| POST | `/:typeNum/loop/` | Add slide to loop |
| DELETE | `/:typeNum/loop/:slideID` | Remove slide from loop |
| POST | `/api/upload-media/:typeNum` | API: Upload store media |
| POST | `/api/upload-media/corp/` | API: Upload corporate media |
| GET | `/:typeNum/DigitalSignSyncApp/` | Sync app: Get version |
| POST | `/:typeNum/DigitalSignSyncApp/` | Sync app: Download |

### Database Tables

| Table | Database | Purpose |
|-------|----------|---------|
| `dsSlides` | Store DB | Store-specific slides |
| `dsLoop` | Store DB | Loop/playlist entries |
| `corpSlides` | Global DB | Corporate slides |
| `hbSlides` | Global DB | Hipbone/partner slides |
| `digitalSignSchedule` | Global DB | Schedule tracking |
| `DigitalSignSync` | Store DB | Sync app versions |

### Slide Types

| Type | Value | Description |
|------|-------|-------------|
| Image | 0 | Static image (gif, jpg, png) |
| Video | 1 | Video file (mp4, webm) |
| Queue | 3 | Live queue display |

### Slide Sources (slideUploader)

| Source | Value | Database |
|--------|-------|----------|
| Store | 0 | Store-specific DB |
| Corporate | 1 | Global DB (corpSlides) |
| Hipbone | 2 | Global DB (hbSlides) |