# Wallboard Scheduling System - Complete Architecture

## Scheduling Architecture Overview

Wallboard uses a multi-layered scheduling system operating at different levels:
1. **Item-level scheduling** within playlists/channels
2. **Content-level scheduling** for entire playlists/contents  
3. **Page-level scheduling** within multi-page content (simple mode only, complex coming soon)
4. **Schedule overrides** for time-based content replacement

## Universal Scheduling Rules & Logic

### Include vs Exclude Rules
- **Include**: Content plays ONLY during specified times (whitelist approach)
- **Exclude**: Content plays EXCEPT during specified times (blacklist approach)

### Scheduling Modes Available Everywhere

#### Simple Scheduling
- **Basic controls**: Start date, End date, Time range, Days of week
- **Single rule**: One unified schedule per item

#### Complex Scheduling (where available)
- **Multiple rules**: Can add multiple date/time combinations per item
- **Rule types**: Specific dates, Date ranges, each with Include/Exclude toggle
- **OR logic**: Item active if ANY scheduling rule is currently active

### Device-Side Evaluation & AND Logic
- **Real-time calculation**: All scheduling evaluated on device in real-time using device's local timezone
- **AND logic inheritance**: Parent schedule AND child schedule both must be active
- **Nested scheduling**: All layers must be active for content to play (always restrictive, never expansive)

## Playlist Item Scheduling

### Per-Item Scheduling in Playlists
Every element in a playlist can be individually scheduled with its own rules and constraints.

### Playbook Mode Integration
Each playlist item has a playback mode affecting scheduling behavior:

#### Default Mode
- **Standard rotation**: Plays as part of normal playlist sequence when scheduled
- **Shares playlist time**: Rotates with other Default mode items according to duration settings

#### Exclusive Mode  
- **Takes over playlist**: When Exclusive item is active, ONLY Exclusive items play
- **Suppresses others**: All Default and Fallback items are ignored during Exclusive periods
- **Multiple Exclusives**: If multiple Exclusive items are active simultaneously, ALL play in rotation
- **Page targeting aware**: Exclusive takes over only on screens eligible for its page; configured tags/Folders or a device Quick Filter narrow that eligibility.
- **Schedule dependent**: Exclusive behavior only applies when item's schedule is active

#### Fallback Mode
- **Safety net content**: Plays ONLY when no Default or Exclusive items are active
- **Multiple Fallbacks**: If multiple Fallback items exist, ALL play in rotation during fallback periods
- **Independent scheduling**: Fallback items can have their own schedules
- **Last resort**: Prevents blank screens when no other content is eligible

### Playlist Evaluation Priority:
1. **Check for active Exclusive items** (scheduled + page eligible for this screen)
   - If found: Play ONLY Exclusive items, ignore everything else
2. **Check for active Default items** (scheduled + page eligible for this screen)
   - If found: Play Default items in normal rotation
3. **Check for active Fallback items** (scheduled + page eligible for this screen)
   - If found: Play Fallback items as safety net
4. **No active items**: Blank screen or "No Content" message

### Practical Playback Mode Examples

#### Exclusive Takeover:
```
Playlist: "Daily Content"
├── Welcome Message (Default, All day)
├── Lunch Menu (Exclusive, 11:30 AM - 1:30 PM)  
├── Afternoon Promos (Default, 2:00 PM - 6:00 PM)
└── Closing Message (Fallback, All day)

Timeline:
- 10:00 AM: Welcome Message plays (Default mode)
- 12:00 PM: ONLY Lunch Menu plays (Exclusive suppresses Welcome)
- 3:00 PM: Welcome + Afternoon Promos rotate (Default mode)
- 7:00 PM: Closing Message plays (Fallback - no active Defaults)
```

#### Fallback Safety Net:
```
Playlist pages targeted by device tags:
├── Store A Promo (Default, tags: "store-a")
├── Store B Promo (Default, tags: "store-b")  
├── Generic Content (Fallback, no tags)

On Store C device (no matching tags):
- Store A/B promos don't play (tag mismatch)
- Generic Content plays as fallback (prevents blank screen)
```

## Content Page-Level Scheduling

### Multi-Page Content Scheduling
Individual pages within Content can be scheduled (simple mode only):
- **Page-specific schedules**: Each page can have its own scheduling rules
- **AND logic with content**: Page schedule must align with Content-level schedule
- **Complex scheduling**: Coming soon for content pages

### Dynamic Page Visibility:
```
Corporate Content (5 pages):
├── Page 1: Logo/Welcome (always visible)
├── Page 2: Morning briefing (7-9 AM only) 
├── Page 3: Daily KPIs (business hours)
├── Page 4: Lunch menu (11:30-13:30)
└── Page 5: End of day summary (16:00-18:00)

Navigation behavior:
- 8:00 AM: User sees Page 1, 2, 3 (lunch menu hidden)
- 12:00 PM: User sees Page 1, 3, 4 (morning briefing hidden)
- 17:00 PM: User sees Page 1, 3, 5 (lunch + morning hidden)
```

## Schedule Overrides - Time-Based Content Replacement

### What Are Schedules?
**Schedules** are temporary content overrides that replace a device's assigned content based on time/conditions.

### Schedule Configuration (3-Step Process):

#### 1. What CONTENT to schedule?
- Select exactly **one content item**: Playlist, Slide, or Content
- Cannot schedule multiple items in a single Schedule

#### 2. When to play?
- **Same scheduling system** as other content (simple/complex modes)
- **Include/Exclude rules** available
- **Multiple time rules** supported with OR logic

#### 3. Where to play?
**Targeting options**:
- **Specific devices**: Manual device selection from list
- **Dynamic targeting**: Folder + Tag + Team filtering with Any/All match logic
- **Quick filters**: Pre-created complex device queries (WBQL support)

### Schedule Priority & Content Hierarchy

#### Device Content Priority (highest to lowest):
1. **Emergency Content** (always absolute priority - CAP integration supported)
2. **Active Schedule** (priority-based override, GUID-based tie-breaking for same priority)
3. **Base Assigned Content** (playlist/slide/content)

#### Schedule Priority System:
- **Priority numbers**: Higher number = higher priority (Priority 2 is higher than Priority 1)
- **Tie-breaker**: Same priority resolved by creation date (one that has been created first will be applied)
- **Complete override**: Active Schedule replaces base content entirely
- **Fallback**: When Schedule ends, device returns to original assigned content

### Schedule Examples

#### Simple Override:
```
Device: Lobby Screen  
Base: "Daily Playlist"
Schedule: "Fire Drill Instructions" (Priority 1, Today 2-2:30 PM)
Result: Fire drill content during drill, returns to daily playlist after
```

#### Multiple Schedule Conflict:
```
Device: Break Room TV
Base: "Employee News"  
Schedule A: "Lunch Menu" (Priority 1, 11:30 AM-1 PM)
Schedule B: "CEO Announcement" (Priority 2, 12-12:15 PM)
Result: 
- 11:30-12:00: Lunch Menu plays
- 12:00-12:15: CEO Announcement plays (higher priority)
- 12:15-1:00: Lunch Menu resumes
- After 1:00: Returns to Employee News
```

## Channel and Sub-Channel Scheduling

### Channel-Level Scheduling (Not Item-Level)
- **Channels/Sub-channels**: Have their own scheduling rules that apply to the entire channel
- **Channel scheduling**: Controls when the entire channel is active/inactive
- **Sub-channel scheduling**: Controls when specific sub-channels within a channel are active
- **No individual item scheduling within channels**: Unlike playlists, channel items cannot be individually scheduled

### Nested Scheduling Evaluation in Channels:
**Multi-layer AND logic**:
1. **Channel schedule** must be active
2. **Sub-channel schedule** (if applicable) must be active  
3. **Playlist scheduling** (if channel contains playlists) is evaluated within active channels
4. **Playlist item scheduling** (within playlists inside channels) is evaluated last

### Channel Schedule Interaction Examples:
```
Channel A (Business hours: 9 AM - 5 PM)
├── Contains Playlist X with item scheduled (Lunch: 12-1 PM)
└── Result: Item plays only 12-1 PM (intersection of channel + playlist item schedules)

Channel B (Weekend only: Sat-Sun)  
├── Sub-channel C (Business hours: 9 AM - 5 PM)
└── Result: Sub-channel C never plays (no schedule overlap)

Channel D (All week)
├── Contains Playlist Y (Weekdays only)
│   └── Item Z (Morning only: 8-10 AM)  
└── Result: Item Z plays weekdays 8-10 AM (all three schedules active)
```

### Scheduling Hierarchy in Channels:
```
1. Channel Schedule (controls entire channel availability)
   ├── 2. Sub-channel Schedule (controls sub-channel availability within channel)
   │   ├── 3. Playlist Schedule (if channel contains playlists)
   │   │   └── 4. Playlist Item Schedule (individual item timing)
   │   └── 3. Direct Content Schedule (if channel contains direct content)
   └── All levels must be active simultaneously (AND logic)
```

### Playlist Integration in Channels:
When playlists are added to channels:
- **Channel schedule**: Applied as overarching time window
- **Playlist schedule**: Applied within channel's active time  
- **Playlist item schedules**: Applied within playlist's active time
- **Device targeting**: Channel device tags apply alongside each Playlist page's targeting rule (tags/Folders or one device Quick Filter, when configured).
- **Collection playback modes**: (one-item, all-item) respected within scheduling constraints
- **Playback modes**: (Default, Exclusive, Fallback) operate within scheduled time windows

## Emergency Content & CAP Integration

### Emergency Content Setup:
- **Manual assignment**: Emergency content must be pre-assigned to devices
- **CAP integration**: Common Alerting Protocol can automatically trigger pre-assigned emergency content
- **Dynamic content**: Emergency content can use CAP as data source for live alert details
- **Absolute priority**: Emergency content always overrides Schedules and base content

### CAP Emergency System Workflow:

#### Setup Phase (Manual):
1. Admin creates Emergency Content (slide/content)
2. Admin assigns Emergency Content to devices  
3. Admin configures CAP data source integration
4. Emergency Content uses CAP data source for dynamic content

#### Runtime Phase (Automatic):
1. CAP alert issued (weather, safety, etc.)
2. System automatically switches devices to Emergency Content mode
3. Emergency Content displays with live CAP data (alert text, severity, instructions)
4. When CAP alert expires → devices return to normal content

### Smart Emergency Integration:
```
Emergency Content: "Weather Alert Display"
├── CAP Data Source: Live weather alerts
├── Pre-assigned to: All lobby devices
└── Content dynamically shows:
    ├── Alert type (tornado, flood, etc.)
    ├── Severity level  
    ├── Instructions ("Seek shelter immediately")
    └── Duration/expiry time
```

## Scheduling Best Practices & Edge Cases

### Nested Scheduling Strategy:
- **Corporate level**: Broad time windows (business hours)
- **Regional level**: More specific timing (regional campaigns)
- **Local level**: Detailed scheduling (store-specific promotions)
- **Item level**: Precise timing (lunch menu items)

### Common Scheduling Conflicts:
- **Overlapping Exclusives**: Multiple exclusive items → all play together
- **Empty time slots**: No active items → fallback content activates
- **Timezone changes**: Device-side evaluation handles DST and timezone shifts
- **Network outages**: Offline scheduling continues seamlessly

### Performance Considerations:
- **Complex scheduling**: Evaluated real-time on device (no performance impact)
- **Multiple rules per item**: OR logic evaluation lightweight
- **Cross-page scheduling**: Each page evaluated independently
- **State persistence**: Scheduling state maintained during device restart