# Wallboard Channel System - Complete Architecture

## Channel Architecture & Content Types

### Channel Content Rules
Channels can only contain **ONE** type of content (no mixing):
- **Content**: Slides, playlists, multi-page content, schedules
- **Media**: Images, videos, PDFs  
- **Sub channel**: Sub-channel groups and sub-channels only
- **SSP (Vistar Media)**: Programmatic advertising integration

### Content Assignment Methods (All Channel Types)
All channel types support flexible content assignment:

#### Specific Assignment:
- **Manual selection**: Choose exact content items, media files, or sub-channels
- **Direct control**: Explicitly define what plays in the channel

#### Dynamic with Tags and Folder:
- **Tag-based selection**: Content/media automatically included based on tags
- **Folder-based selection**: Content/media from specific folders automatically included  
- **Team filtering**: Restrict to content/media from specific teams
- **Automatic updates**: New content matching criteria automatically included

#### Dynamic with Quick Filter:
- **Advanced filtering**: Use pre-created Quick Filters for complex selection logic
- **WBQL support**: Complex queries for sophisticated content/media selection
- **Reusable filters**: Same filter logic applicable across multiple channels

### Channel Structure Levels

#### 1. Main Channel (Root Level)
- **Content container**: Holds sub-channel groups, sub-channels, or direct items
- **Balancing participation**: Has order and saturation for channel widget balancing
- **Device targeting**: Independent "where to play" settings (same as Schedule system)

#### 2. Sub-channel Groups (Mandatory Wrapper)
- **Organizational containers**: Group related sub-channels together
- **Mandatory structure**: Sub-channels cannot be added directly to main channels
- **Order within main channel**: Determines group sequence

#### 3. Sub-channels  
- **Content containers**: Hold actual content items (slides, content, media)
- **Individual targeting**: Each has device tags and scheduling (more sophisticated than playlist tags)
- **Order within group**: Determines sub-channel sequence within group
- **No saturation**: Only main channels participate in saturation balancing

## Channel Widget Targeting System

### Two-Dimensional Tag Filtering
Channel widgets use sophisticated filtering to determine content inclusion:

#### Main Channel Filtering: "Channels with tags only"
- **OFF** (default): Includes ALL channels + channels matching specified tags
- **ON**: Includes ONLY channels with matching tags

#### Sub-Channel Filtering: "Sub channels with tags only"  
- **OFF** (default): Includes ALL sub-channels within selected channels
- **ON**: Includes ONLY sub-channels matching the specified tags

### Dynamic Tag Management (Real-time)
Channel widget tags can be **dynamically updated during playback**:

#### Dynamic Tag Sources:
- **AI Camera integration**: Live analysis updates tags based on detected scenarios
- **IoT Sensors**: Environmental or operational data triggers tag changes
- **Live API feeds**: External systems push tag updates via API
- **Business systems**: POS data, inventory levels, customer analytics

## Channel Playback Logic & Multi-Level Control

### Sequential Channel Playback
Channels in channel widgets play **sequentially**, not simultaneously:
- **Order-based sequence**: Lower order number plays first
- **Channel dominance**: Channel-level "playback slot" setting overrides all nested logic
- **Saturation balancing**: Controls relative time/items between main channels

### Multi-Level Playback Control Settings

#### Channel Widget → Main Channel Level:
- **Playback slot options**: One page, Specific number of pages/items, All contents
- **Slot duration/limits**: Time and item limits per slot
- **Balance modes**: Play time (duration-based) vs Played items (count-based)
- **Balance units** (items mode): Single item vs Playback slot

#### Main Channel → Sub-Channel Group Level:
**Group playback options**:
- **One item**: Switch to next group after 1 item from current group
- **Specific number of items**: Switch after N items from current group
- **All groups**: Complete entire group before switching to next group

**Group "Play" behavior**:
- **"One sub channel item"**: Play one item from first sub-channel in group, then switch to next main channel
- **"All sub channels"**: Cycle through all sub-channels in the group, each contributing according to its individual settings

#### Sub-Channel Level (Sub-Channel Group → Individual Sub-Channels):
**Playback slot options**:
- **One page**: Switch to next sub-channel after each page/item
- **Specific number of pages**: Switch after N pages from current sub-channel
- **All contents**: Complete entire sub-channel before switching to next

## Critical Architectural Principle: "All" Settings Respect Lower Level Limits

### Universal Rule
When any level is set to "All" (All groups, All sub channels, All contents), it does NOT override lower-level settings. Instead, it orchestrates through all elements while respecting each element's individual limits.

### Key Examples:

#### Group set to "All sub channels" + Sub-channel set to "2 pages":
- System cycles through all sub-channels in group
- Each sub-channel contributes exactly 2 pages (its own setting)
- Then moves to next sub-channel
- Continues until all sub-channels have contributed their 2 pages each

#### Sub-channel set to "All contents" + Embedded playlist set to "One item":
- System plays through all contents in sub-channel
- But embedded playlist only contributes 1 item per turn (its own setting)
- Respects the playlist's collection playback mode

### Channel Dominance Exception
**Only the main channel-level "playback slot" setting can override everything below.** All other "All" settings work as orchestration commands, not override commands.

### Nested Settings Respect Chain:
```
Channel Widget: "3 items" (OVERRIDES everything - channel dominance)
├── Main Channel: "All groups" (orchestrates, doesn't override)
├── Group: "All sub channels" (orchestrates, doesn't override)  
├── Sub-channel: "2 pages" (defines its contribution limit)
└── Embedded Playlist: "One item" (defines its contribution limit)

Result: System uses all groups and all sub-channels, but each contributes 
according to its own settings, within the 3-item channel limit.
```

## Detailed Playback Flow Example

```
Channel Widget: Switch after 4 items
Main Channel A: "Corporate Communications" (saturation: 2)
├── Group 1: "Regional" (set to "All sub channels") 
│   ├── Sub-channel: "North" (order: 1, set to "One page")
│   │   ├── Content 1 (3 pages)
│   │   └── Content 2 (2 pages)  
│   └── Sub-channel: "South" (order: 2, set to "2 pages")
│       ├── Content 3 (4 pages)
│       └── Content 4 (1 page)
├── Group 2: "Corporate" (set to "One sub channel item")
│   └── Sub-channel: "Executive" (set to "All contents")
│       └── Content 5 (5 pages)

Playback Flow - Group 1 with "All sub channels":
1. North Content 1 Page 1 (North contributes 1 page per its setting)
2. South Content 3 Page 1 (South starts its 2-page contribution)  
3. South Content 3 Page 2 (South completes its 2-page limit)
4. North Content 1 Page 2 (North contributes next 1 page)
[Channel limit reached: 4 items - switch to next main channel]

Key Insight: Group's "All sub channels" orchestrated through both sub-channels, 
but each contributed exactly according to its individual setting 
(North: 1 page, South: 2 pages).
```

## Balancing System Details

### Saturation Calculation (Main Channels Only):
- **Play time balancing**: Exact duration ratios (Channel A saturation 3 = 3x time vs saturation 1)
- **Played items + Playback slot**: Saturation applies to slots (may differ from item ratios)  
- **Played items + Single item**: Saturation applies directly to items (exact ratios)

## Dynamic Channel Control

### Webhook-Controllable Parameters:
- **Main channel saturation**: Real-time weight adjustments between main channels
- **Main channel order**: Real-time priority changes between main channels  
- **Sub-channel order**: Sequence changes within groups
- **Immediate effect**: Changes apply without restart

## Vistar Media SSP Integration

### SSP Channel Type:
- **Wallboard as SSP**: Wallboard functions as Supply-Side Platform in programmatic advertising ecosystem
- **External DSP integration**: Content sourced from external Demand-Side Platforms via Vistar Media
- **Real-time asset delivery**: Assets requested and delivered at playback time, not pre-cached

### Vistar Playback Flow:
```
Playback reaches Vistar channel → 
Request sent to Vistar servers → 
Asset delivered from external DSP → 
Content plays on device → 
Playback completion reported back to Vistar
```

### Channel Integration:
- **Same channel settings apply**: Order, saturation, scheduling, device targeting work identically
- **Mixed content strategies**: External DSP content can be balanced with internal content via channel saturation
- **Unified management**: Vistar channels participate in normal channel widget orchestration

## Team-Based Channel Management

### Distributed Enterprise Control:

#### Team Assignment Hierarchy:
- **Main Channels**: Corporate/power user teams (strategic control)
- **Sub-Channel Groups**: Regional management teams (geographic organization)
- **Sub-Channels**: Local teams (tactical content management)

#### Enterprise Benefits:
- **Scalable permissions**: Team structure mirrors business organization
- **Global consistency**: Corporate controls saturation/balance, locals control content
- **Flexible collaboration**: Isolation when needed, sharing when beneficial
- **Clear boundaries**: Team membership = access rights

## Offline-First Architecture

### Hybrid Computation Model:

#### Server-Side (Online):
- **Complex targeting calculations**: Sophisticated device selection logic
- **Channel assignment optimization**: Which channels go to which devices
- **Global orchestration**: Saturation, order, balancing rules

#### Device-Side (Offline-Capable):
- **Scheduling evaluation**: All time-based calculations  
- **Content playback sequencing**: Order, switching, state management
- **Complete autonomy**: Full functionality without network connection
- **Content pre-caching**: All future playable content stored locally

### Technical Advantages:
- **Bandwidth optimization**: Bulk content delivery vs real-time streaming
- **Reliability**: Network outages don't interrupt content playback
- **Performance**: Local scheduling calculations, no server dependency
- **Scalability**: Distributed computation across thousands of devices