InstaAlert Engine™ — Multi-Endpoint Orchestration

1. Generic Device Model

Instead of assuming "screen," InstaAlert Engine models endpoints as generic Device objects with standardized properties:

Device Object Schema

{
  "id": "device-uuid-here",
  "deviceKey": "LAX-TERMB-PA-001",
  "type": "pa_system",
  "name": "Terminal B PA Zone 1",
  "location": {
    "tenantId": "tenant-lax-uuid",
    "campusId": "campus-lax-uuid",
    "buildingId": "building-termb-uuid",
    "floorId": "floor-1-uuid",
    "zoneId": "zone-gates-15-20-uuid"
  },
  "capabilities": ["audio_output", "text_to_speech", "volume_control"],
  "status": "online",
  "lastSeen": "2024-11-29T10:30:00Z",
  "metadata": {
    "manufacturer": "Bose",
    "model": "FreeSpace DS 100SE",
    "firmwareVersion": "2.4.1"
  }
}

Device Types at an Airport

📺

Display Screen

type: screen

Gate info displays, emergency alert screens, wayfinding kiosks

display_alert display_image display_video show_evacuation_map

🔊

PA System

type: pa_system

Overhead speakers, zone audio, emergency broadcast

audio_output text_to_speech play_tone volume_control

🌡️

HVAC Controller

type: hvac

Air handling units, smoke dampers, pressurization

smoke_control pressurize_stairwell shutdown_zone

🚪

Door Controller

type: door_controller

Access control, emergency egress, lockdown

unlock_door lock_door hold_open report_status

📡

Digital Signage

type: signage_player

Video walls, menu boards, advertising displays

display_alert interrupt_content display_video

2. Device Registration Examples

Each vendor registers their devices with InstaAlert Engine. Here are complete Device JSON objects for different endpoint types at LAX Terminal B:

Screen (Emergency Display)

{
  "id": "d8f7e6c5-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
  "deviceKey": "LAX-TERMB-SCREEN-G15",
  "type": "screen",
  "name": "Gate 15 Emergency Display",
  "location": {
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "campusId": "660e8400-e29b-41d4-a716-446655440001",
    "buildingId": "770e8400-e29b-41d4-a716-446655440002",
    "buildingCode": "TERMINAL-B",
    "floorId": "880e8400-e29b-41d4-a716-446655440003",
    "floor": 1,
    "zoneId": "990e8400-e29b-41d4-a716-446655440004"
  },
  "capabilities": ["display_alert", "display_image", "show_evacuation_map", "play_audio"],
  "status": "online",
  "connectionType": "websocket"
}

PA System (Audio Zone)

{
  "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "deviceKey": "LAX-TERMB-PA-ZONE1",
  "type": "pa_system",
  "name": "Terminal B Concourse PA Zone 1",
  "location": {
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "campusId": "660e8400-e29b-41d4-a716-446655440001",
    "buildingId": "770e8400-e29b-41d4-a716-446655440002",
    "buildingCode": "TERMINAL-B",
    "floorId": "880e8400-e29b-41d4-a716-446655440003",
    "floor": 1
  },
  "capabilities": ["audio_output", "text_to_speech", "play_tone", "volume_control"],
  "status": "online",
  "connectionType": "webhook",
  "webhookUrl": "https://pa-vendor.example.com/api/zones/termb-1/alert"
}

Door Controller (Emergency Egress)

{
  "id": "b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "deviceKey": "LAX-TERMB-DOOR-EXIT3",
  "type": "door_controller",
  "name": "Terminal B Emergency Exit 3",
  "location": {
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "campusId": "660e8400-e29b-41d4-a716-446655440001",
    "buildingId": "770e8400-e29b-41d4-a716-446655440002",
    "buildingCode": "TERMINAL-B",
    "floorId": "880e8400-e29b-41d4-a716-446655440003",
    "floor": 1
  },
  "capabilities": ["unlock_door", "lock_door", "hold_open", "report_status"],
  "status": "online",
  "connectionType": "webhook",
  "webhookUrl": "https://access-control.example.com/api/doors/exit3/command"
}

3. Capability-Based Alert Routing

The Alerts API extends beyond "send to screens" to support capability-based targeting. You specify which capabilities are required, and the routing engine finds all devices that match.

Fire Panel

Trigger Source

→

POST /api/v1/alerts
capabilities + location

→

Routing Engine
Match devices

→

Screens

display_alert

PA Systems

audio_output

Door Controllers

unlock_door

HVAC

smoke_control

Enhanced Alert Request with Capabilities

// POST /api/v1/alerts
{
  "schoolCode": "AIRPORT-LAX",
  "alertType": "fire",
  "message": "Fire alarm activated - Terminal B. Evacuate immediately via nearest exit.",
  
  // Location targeting (existing)
  "buildingCode": "TERMINAL-B",
  "floor": 1,
  
  // NEW: Capability-based targeting
  "targetCapabilities": {
    "required": ["display_alert"],           // Device MUST have this
    "preferred": ["show_evacuation_map"],    // Include if available
    "actions": {                              // Capability-specific payloads
      "audio_output": {
        "message": "Attention. Fire alarm. Evacuate Terminal B immediately.",
        "tone": "evacuation",
        "repeat": 3
      },
      "unlock_door": {
        "mode": "emergency_egress",
        "holdOpen": true
      },
      "smoke_control": {
        "mode": "pressurize_stairwells"
      }
    }
  }
}

Routing Engine Logic

Step	Action	Result
1	Resolve location: `TERMINAL-B, Floor 1`	Campus Graph returns building UUID + floor UUID
2	Query devices at location with `display_alert` capability	12 screens found
3	Query devices with `audio_output` in actions	4 PA zones found
4	Query devices with `unlock_door` in actions	8 emergency exits found
5	Query devices with `smoke_control` in actions	2 HVAC controllers found
6	Dispatch to all 26 devices with capability-specific payloads	WebSocket to screens, webhooks to others

4. Campus Graph Location Resolution

The Campus Graph API remains the authoritative source for location hierarchy. Devices are registered to locations, and the routing engine uses Campus Graph to resolve which devices should receive alerts.

Location Hierarchy

Tenant (LAX Airport Authority)
  └── Campus (LAX International)
        └── Building (Terminal B)
              └── Floor (Level 1 - Departures)
                    └── Zone (Gates 15-20)
                          └── Devices
                                ├── Screen: Gate 15 Display
                                ├── Screen: Gate 16 Display
                                ├── PA: Zone 1 Speakers
                                └── Door: Emergency Exit 3

Device Location Query

GET /api/v1/graph/devices

// Query: All devices in Terminal B with display_alert capability
GET /api/v1/graph/devices?buildingCode=TERMINAL-B&capability=display_alert

// Response
{
  "devices": [
    {
      "id": "d8f7e6c5-4b3a-...",
      "deviceKey": "LAX-TERMB-SCREEN-G15",
      "type": "screen",
      "name": "Gate 15 Emergency Display",
      "capabilities": ["display_alert", "show_evacuation_map"],
      "location": {
        "building": "Terminal B",
        "floor": 1,
        "zone": "Gates 15-20"
      },
      "status": "online"
    },
    // ... 11 more screens
  ],
  "total": 12
}

Resolve Location from Device Key

GET /api/v1/graph/locations/resolve

// Query: Resolve full location path from device key
GET /api/v1/graph/locations/resolve?identifier=LAX-TERMB-PA-ZONE1

// Response
{
  "device": {
    "id": "a1b2c3d4-5e6f-...",
    "deviceKey": "LAX-TERMB-PA-ZONE1",
    "type": "pa_system"
  },
  "locationPath": {
    "tenant": { "id": "...", "name": "LAX Airport Authority" },
    "campus": { "id": "...", "name": "LAX International" },
    "building": { "id": "...", "name": "Terminal B", "code": "TERMINAL-B" },
    "floor": { "id": "...", "number": 1, "name": "Level 1 - Departures" },
    "zone": null
  }
}

5. Full Orchestration Example: Fire Evacuation

This example shows a complete multi-endpoint orchestration for a fire evacuation in Terminal B. A single API call coordinates screens, PA, doors, and HVAC.

Step 1: Fire Panel Triggers Alert

curl -X POST https://instaalert.app/api/v1/alerts \
  -H "Authorization: Bearer sk_live_FIRE_PANEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schoolCode": "AIRPORT-LAX",
    "alertType": "fire",
    "message": "FIRE EMERGENCY - Terminal B Level 1. Evacuate via nearest exit.",
    "buildingCode": "TERMINAL-B",
    "floor": 1,
    "targetCapabilities": {
      "required": ["display_alert"],
      "actions": {
        "audio_output": {
          "message": "Attention. Fire emergency. Evacuate Terminal B Level 1 immediately. Use nearest emergency exit.",
          "tone": "evacuation",
          "repeat": 3,
          "volume": 100
        },
        "unlock_door": {
          "mode": "emergency_egress",
          "holdOpen": true,
          "logReason": "fire_evacuation"
        },
        "smoke_control": {
          "mode": "pressurize_stairwells",
          "closeFireDampers": true
        },
        "show_evacuation_map": {
          "alertType": "fire"
        }
      }
    }
  }'

Step 2: InstaAlert Engine Response

{
  "success": true,
  "alertId": "alert-1701234567890",
  "orchestration": {
    "location": {
      "building": "Terminal B",
      "floor": 1,
      "resolved": true
    },
    "devicesSummary": {
      "total": 26,
      "byType": {
        "screen": { "targeted": 12, "delivered": 12, "method": "websocket" },
        "pa_system": { "targeted": 4, "delivered": 4, "method": "webhook" },
        "door_controller": { "targeted": 8, "delivered": 8, "method": "webhook" },
        "hvac": { "targeted": 2, "delivered": 2, "method": "webhook" }
      },
      "byCapability": {
        "display_alert": 12,
        "show_evacuation_map": 12,
        "audio_output": 4,
        "unlock_door": 8,
        "smoke_control": 2
      }
    },
    "timestamp": "2024-11-29T10:15:30.000Z"
  }
}

Step 3: Webhook Delivery to Vendor Systems

Each vendor system receives a webhook with their capability-specific payload:

PA System Webhook

{
  "alertId": "alert-170...",
  "deviceKey": "LAX-TERMB-PA-ZONE1",
  "action": "audio_output",
  "payload": {
    "message": "Attention. Fire...",
    "tone": "evacuation",
    "repeat": 3,
    "volume": 100
  }
}

Door Controller Webhook

{
  "alertId": "alert-170...",
  "deviceKey": "LAX-TERMB-DOOR-EXIT3",
  "action": "unlock_door",
  "payload": {
    "mode": "emergency_egress",
    "holdOpen": true,
    "logReason": "fire_evacuation"
  }
}

Result: Coordinated Emergency Response

Screens: Display fire alert + floor-specific evacuation map
PA: Broadcast evacuation message 3 times at full volume
Doors: All emergency exits unlocked and held open
HVAC: Stairwells pressurized, fire dampers closed
Audit Log: Complete record of all 26 device actions

6. Standard Capabilities Reference

InstaAlert Engine defines standard capability identifiers that vendors use when registering devices. This ensures interoperability across different vendor systems.

Capability	Description	Device Types
`display_alert`	Can show visual alert message on screen	screen, signage_player, kiosk
`display_image`	Can display static images	screen, signage_player
`display_video`	Can play video content	screen, signage_player, video_wall
`show_evacuation_map`	Can display floor-specific evacuation maps	screen, kiosk
`audio_output`	Can produce audio (announcements, tones)	pa_system, screen, speaker
`text_to_speech`	Can convert text to spoken audio	pa_system, speaker
`play_tone`	Can play alert tones (evacuation, all-clear)	pa_system, speaker, siren
`unlock_door`	Can unlock/release door	door_controller
`lock_door`	Can lock/secure door	door_controller
`hold_open`	Can hold door in open position	door_controller
`smoke_control`	Can activate smoke control modes	hvac, damper_controller
`pressurize_stairwell`	Can pressurize stairwell for fire safety	hvac
`lighting_control`	Can control lighting (flash, dim, color)	lighting_controller, smart_bulb
`report_status`	Can report device status back to platform	all device types

Custom Capabilities

Vendors can register custom capabilities using namespaced identifiers (e.g., vendor:custom_action). Contact InstaAlert support for capability registration.

7. Summary: Beyond Screens

InstaAlert Engine is not a "digital signage" platform. It's a safety infrastructure routing layer that can orchestrate any endpoint capable of participating in an emergency response:

Generic Device Model — Any endpoint is a Device with type, location, and capabilities
Capability-Based Routing — Target devices by what they can do, not what they are
Campus Graph Integration — Location hierarchy resolves where devices are
Multi-Vendor Orchestration — One API call coordinates screens, PA, doors, HVAC
Unified Audit Trail — Every device action logged for compliance

The Platform Promise

When you walk into an airport with InstaAlert Engine deployed, every PA speaker, every emergency display, every door controller, and every HVAC system can participate in a coordinated emergency response — all through a single API.