# Internal Data Source Actions & Webhook System

> Advanced manipulation capabilities for internal data sources including webhook actions, device-side API calls, and distributed state management.

---

## Action System Architecture

### Dual Execution Paths:
1. **External Webhook Calls**: External systems trigger actions via webhook URLs
2. **Device-Side API Calls**: Devices call same actions directly via internal API (not as webhooks)

**Key Insight**: Same action logic accessible both externally (webhooks) and internally (device API), enabling both remote control and self-modification patterns.

---

## Internal Data Source Action Types

### 1. **Replace Entire Data Source**
- **Action**: Complete state overwrite
- **Input**: Full JSON payload
- **Effect**: Replaces entire data source content with provided JSON
- **Use case**: Complete state reset, bulk updates, initial data load

### 2. **Increment Number Value**
- **Action**: Increase numeric value at specific path
- **Selector syntax**: Dot-notation path (e.g., `stats.visitors.count`)
- **Input**: Selector path + increment amount
- **Validation**: Target must be numeric type
- **Use case**: Counters, score tracking, inventory increases

### 3. **Decrement Number Value**
- **Action**: Decrease numeric value at specific path
- **Selector syntax**: Dot-notation path (not JSON Path)
- **Input**: Selector path + decrement amount
- **Validation**: Target must be numeric type
- **Use case**: Inventory reduction, countdown timers, resource consumption

### 4. **Delete Value at Key**
- **Action**: Remove specific key-value pair
- **Selector syntax**: Dot-notation to target key
- **Effect**: Removes the key and its value from JSON structure
- **Use case**: Clearing optional fields, removing expired data

### 5. **Clear Array**
- **Action**: Empty an array while preserving the array itself
- **Selector syntax**: Path to array
- **Result**: Array becomes `[]`
- **Use case**: Resetting lists, clearing queues, batch cleanup

### 6. **Insert into Array**
- **Action**: Add JSON element to array
- **Input**: Array selector + JSON element to insert
- **Position options**: 
  - Append to end (default)
  - Insert at specific index
  - Prepend to beginning
- **Use case**: Adding queue items, building lists, logging events

### 7. **Remove from Array by Index**
- **Action**: Delete array element at specific position
- **Input**: Array selector + index number
- **Index handling**: 
  - Positive index: Count from start (0-based)
  - Negative index: Count from end (-1 = last element)
- **Use case**: Queue processing, removing completed items

### 8. **Rotate Array**
- **Action**: Limit array size by removing old elements
- **Configuration**:
  - Maximum array size
  - Removal strategy (FIFO/LIFO)
- **Behavior**: When array exceeds max size, oldest/newest elements removed
- **Use case**: Event logs with size limits, rolling buffers, recent activity tracking

### 9. **Merge JSON Objects**
- **Action**: Overlay one JSON object onto another
- **Merge behavior**:
  - New values override existing values for same keys
  - New keys are added
  - Unmentioned keys remain unchanged
- **Deep merge**: Nested objects are merged recursively
- **Use case**: Partial updates, configuration overlays, incremental changes

---

## Selector Syntax

### Dot-Notation Path System:
- **Format**: `level1.level2.level3.targetKey`
- **NOT JSON Path**: Custom dot-notation syntax (not standard JSON Path)
- **Array access**: `array.0` for first element, `array.1` for second, etc.
- **Nested arrays**: `data.items.2.subItems.0.value`

### Examples:
```
Simple value: "temperature"
Nested object: "sensor.readings.current"
Array element: "playlist.items.0.title"
Deep nesting: "locations.store1.departments.electronics.inventory.count"
```

---

## External Data Source Actions

### **Force Refresh**
- **Action**: Trigger immediate data source refresh
- **Target**: External data sources only
- **Behavior**: Bypasses scheduled refresh, initiates immediate fetch
- **No data submission**: Only triggers refresh, doesn't provide data
- **Use case**: 
  - Event-driven updates instead of polling
  - Manual refresh triggers
  - Dependency-based refresh chains
  - Webhook from source system saying "new data available"

---

## Practical Implementation Patterns

### Multi-Screen State Synchronization:
```
Scoreboard System:
├── Control Tablet Actions:
│   ├── Increment("scores.home", 1) → Updates home score
│   ├── Decrement("timeouts.home", 1) → Uses timeout
│   └── Insert("events", {type: "goal", time: "14:32"})
└── Display Screens:
    ├── Subscribe to same data source
    ├── Real-time updates via WebSocket
    └── Synchronized state across all displays
```

### Queue Management System:
```
Customer Service Queue:
├── Entry Kiosk Actions:
│   ├── Insert("queue", {number: 42, time: now()})
│   └── Increment("stats.dailyCustomers", 1)
├── Service Desk Actions:
│   ├── Remove("queue", 0) → Process first customer
│   └── Increment("stats.served", 1)
└── Waiting Area Display:
    └── Shows live queue from data source
```

### Inventory Tracking:
```
Stock Management:
├── POS Integration (Webhook):
│   ├── Decrement("products.ABC123.stock", soldQuantity)
│   └── Rotate("recentSales", maxSize: 100)
├── Delivery System (Webhook):
│   ├── Increment("products.ABC123.stock", receivedQuantity)
│   └── Merge({lastDelivery: timestamp})
└── Display Updates:
    └── Real-time stock levels on all screens
```

### Event Logging with Rotation:
```
Activity Monitor:
├── Device Actions:
│   ├── Insert("eventLog", {event: "playback_start", device: id})
│   └── Rotate("eventLog", maxSize: 1000) → Keep last 1000 events
└── Benefits:
    ├── Bounded memory usage
    ├── Recent activity always available
    └── Automatic old event cleanup
```

---

## Advanced Use Cases

### Self-Modifying Content:
- **Interactive kiosks**: User interactions modify shared state
- **Voting systems**: Devices increment vote counts directly
- **Check-in systems**: Devices update attendance records
- **Game scoreboards**: Touch screens modify game state

### External System Integration:
- **POS webhooks**: Sales trigger inventory decrements
- **IoT sensors**: Temperature changes trigger threshold actions
- **Calendar systems**: Event changes force refresh external calendar data
- **ERP integration**: Order processing triggers stock updates

### Distributed State Management:
- **No central controller needed**: Any device can modify state
- **Peer-to-peer coordination**: Devices coordinate through shared data source
- **Resilient architecture**: No single point of failure for state updates
- **Real-time synchronization**: All devices see updates immediately

---

## Security & Performance Considerations

### Access Control:
- **Webhook authentication**: Secure webhook URLs with tokens
- **Team permissions**: Edit permissions required for data source modifications
- **Action validation**: Type checking and bounds validation on actions
- **Rate limiting**: Prevent abuse through action rate limits

### Performance Optimization:
- **Atomic operations**: Each action is atomic transaction
- **Efficient selectors**: Dot-notation paths are fast to evaluate
- **Incremental updates**: Only modified paths trigger re-render
- **WebSocket efficiency**: Only deltas transmitted to devices

### Conflict Resolution:
- **Server-side arbitration**: All actions processed sequentially on server
- **Last-write-wins**: For concurrent modifications to same path
- **Transaction ordering**: Webhook timestamp determines processing order
- **Predictable behavior**: Deterministic conflict resolution