Integration Guide#

This guide explains how to integrate the Behavioral Analysis Service into an existing application workflow.

The service is MQTT-driven:

  • Your upstream application publishes analysis requests.

  • The service fetches frames from SeaweedFS, runs pose/pattern analysis (and optional VLM confirmation), then publishes results.

Integration Overview#

Data Flow#

  1. The upstream application stores frames in SeaweedFS.

  2. The upstream application publishes a request message to the BA request topic.

  3. The Behavioral Analysis Service consumes the request and fetches frames.

  4. The service evaluates configured patterns.

  5. The service publishes an outcome message to the BA result topic.

  6. The downstream application consumes the result and applies business actions.

Required Changes in Your Application#

1. Publish Requests to MQTT#

Your application must publish JSON messages to the configured request topic (default: ba/requests).

Required/optional request fields:

Field

Required

Notes

person_id

Yes

Tracked entity identifier

region_id

No

Region/zone identifier

entry_timestamp

No

Used with storage path resolution

scene_id

No

Scene identifier

last_frame_ts

No

Optional cap for frame fetch range

Example payload:

{
  "person_id": "person-042",
  "region_id": "shelf-B",
  "entry_timestamp": "1700001000000",
  "scene_id": "store-01",
  "last_frame_ts": "1700001030000"
}

2. Align the SeaweedFS Frame Path Contract#

Frames must be readable by the service under:

{SEAWEEDFS_BUCKET}/{entity_id}/{region_id}/{entry_timestamp}/frames/{timestamp}.jpg

Note:

  • Bucket name is configurable via SEAWEEDFS_BUCKET.

  • Filenames should preserve timestamp ordering because the service sorts by timestamp name.

3. Consume Result Messages#

Your application (or another downstream consumer) must subscribe to the configured result topic (default: ba/results).

Typical result fields:

Field

Notes

person_id, region_id, entry_timestamp, scene_id, last_frame_ts

Echo/context fields

status

"no_enough_data", "no_match", "suspicious"

confidence

Detection confidence

frames_analyzed

Number of frames processed

vlm_response

Parsed VLM payload or null

pattern_id

Present when pattern matched

description

Pattern description when available

vlm_confirmed

Optional boolean when VLM path is active

Configuration Mapping Checklist#

Ensure your application-side assumptions match service configuration:

  • MQTT broker and topics:

    • MQTT_HOST, MQTT_PORT

    • BA_REQUEST_TOPIC, BA_RESULT_TOPIC

  • SeaweedFS endpoint and bucket:

    • SEAWEEDFS_ENDPOINT, SEAWEEDFS_BUCKET

  • Frame thresholds and fetch behavior:

    • MIN_FRAMES_FOR_DETECTION, MAX_FRAMES_TO_FETCH, POSE_FRAMES_COUNT

  • Model path/device:

    • YOLO_POSE_MODEL, GST_INFERENCE_DEVICE

  • Pattern configuration file:

    • PATTERN_CONFIG_PATH

  • Optional VLM path:

    • VLM_ENABLED, VLM_ENDPOINT, VLM_MODEL_NAME

Use Configuration as the source of truth for variable definitions and defaults.

End-to-End Validation#

Use this sequence after integration:

  1. Confirm connectivity:

    • Service can reach MQTT broker.

    • Service can reach SeaweedFS.

    • If enabled, service can reach OVMS VLM endpoint.

  2. Confirm frame availability:

    Verify frames exist in the expected SeaweedFS path for a known person_id/region_id/entry_timestamp.

  3. Publish one known request:

    Send a request on the configured BA request topic with matching identifiers.

  4. Verify service processing logs:

    Confirm request received, frames fetched, pose analysis executed.

  5. Verify result publication:

    Confirm one output event on BA result topic with expected status and metadata.

Common Integration Pitfalls#

Topic mismatch#

Symptoms:

  • Requests are published but never consumed.

  • No BA results observed.

Checks:

  • Verify publisher topic equals BA_REQUEST_TOPIC.

  • Verify consumer topic equals BA_RESULT_TOPIC.

Frame path mismatch#

Symptoms:

  • Frequent no_enough_data statuses.

Checks:

  • Validate bucket and object key structure match service expectations.

  • Validate that identifiers in the request match identifiers used in the stored frame path.

Cross-container network isolation#

Symptoms:

  • Service starts but cannot reach SeaweedFS/MQTT/OVMS.

Checks:

  • Ensure services share a reachable Docker network.

  • Ensure endpoint hostnames resolve from the behavioral-analysis container.

Configuration drift between environments#

Symptoms:

  • Works in one environment, fails in another.

Checks:

  • Compare .env/.env.local and runtime variables per environment.

  • Reconfirm topic names, bucket name, and model path.