Why it exists
Raw detection streams from the Worlds API arrive at high frequency — potentially hundreds of detections per second across multiple cameras. Processing these directly in the Workflow Builder would cause:- Race conditions — multiple detections for the same track arriving simultaneously
- Incomplete data — individual detections lack context like velocity, dwell time, and zone intersection
- Resource exhaustion — the Workflow Builder would need a WebSocket connection per workflow per camera
What it does
Track state management
The state machine aggregates individual detections into coherent tracks. Each track maintains:- Current position (pixel + geo)
- Velocity (rolling average in px/s and m/s)
- Active zones with dwell times and intersection percentages
- Zone history (previously visited zones)
- Zone sequence (order of zone visits)
- Detection count and age
Signal generation
The state machine emits three signal types to your workflows:Per-datasource ordering
Detections are processed sequentially per data source (camera). This prevents race conditions — your workflow is guaranteed to process signals for a given camera in order.Subscription management
Workflows register with the state machine via webhook URLs. The state machine:- Matches detections against registered subscriptions by data source, object type, and zone
- Delivers only matching signals to each workflow
- Reuses WebSocket connections across subscriptions sharing the same credentials
Architecture
Redis database layout
The state machine uses multiple Redis databases for isolation:Configuration
Key environment variables:Batch processing
For workflows that need complete track data and track-to-track interactions, the state machine supports batch mode:- Stores raw detections in DB3
- Emits tracks only when they expire (complete lifecycle)
- Calculates track-to-track interactions (bounding box overlap, proximity)
- Delivers batch payloads at configurable intervals