Detection Batching Design

Problem

High-frequency cameras (shopping mall ALPRs) generate detections every 1-2 seconds. Without batching:

• 10 high-frequency cameras = ~600 HTTP requests/minute
• Each request incurs connection overhead and latency
• Base64-encoded images in JSON add 33% bandwidth overhead
• Central server faces connection storm during peak traffic

Solution: Time-Window Batching with Size Caps

Edge collectors buffer detections locally and upload in batches using dual triggers:

1. Time Window - Flush after N seconds (prevents stale data)
2. Detection Count - Flush after N detections (prevents memory bloat)
3. Byte Size - Flush after N MB (prevents oversized requests)

Whichever trigger fires first initiates the upload.

Configuration

Parameter	Default	Description
batch_window_seconds	5	Max time to hold detections before flush
batch_max_detections	50	Max detections per batch
batch_max_size_mb	5	Max total payload size

Recommended Settings by Camera Type

Camera Type	Window	Max Detections	Rationale
Residential (low-traffic)	30s	100	Fewer detections, can wait longer
Commercial (medium)	10s	50	Balanced latency/efficiency
Shopping Mall (high)	5s	50	High volume, need frequent uploads

Upload Format

Multipart form-data instead of JSON with base64 images:

• detections field: JSON array of detection metadata (no images)
• image_{n}_full fields: Binary JPEG for full scene images
• image_{n}_crop fields: Binary JPEG for plate crop images

Benefits: - No base64 overhead (saves 33% bandwidth) - Streaming-friendly (lower memory usage) - Standard HTTP multipart handling

Endpoint

POST /api/v1/detections/batch
Content-Type: multipart/form-data
X-API-Key: <collector-api-key>

Backpressure Handling

When central server is slow or unavailable:

1. Exponential Backoff: 30s, 60s, 120s, 240s, 300s (max)
2. Local Buffer: Detections remain in SQLite buffer (7-day retention)
3. Automatic Recovery: Resume normal uploads when connection restored

Deduplication

Detections deduplicated by composite key: - collector_id + camera_id + normalized_plate + 30-second window

Deduplication happens: - On edge: Before adding to batch (saves bandwidth) - On central: Before database insert (handles retries)

Alert Processing

Alert matching is decoupled from detection ingestion:

1. Batch endpoint accepts detections and stores to database
2. Detections queued for async alert processing
3. Alert worker matches against watchlists
4. Matching alerts pushed via WebSocket

This prevents alert matching from slowing detection ingestion during high-volume periods.

Failure Scenarios

Scenario	Behavior
Upload fails	Detections returned to buffer, exponential backoff
Partial batch failure	Failed detections logged, successful detections committed
Central unreachable	Buffer locally up to 7 days, retry with backoff
Oversized batch	Split into smaller batches automatically

Metrics to Monitor

• batch_size_detections - Detections per batch (histogram)
• batch_size_bytes - Bytes per batch (histogram)
• batch_upload_latency_ms - Upload duration (histogram)
• batch_upload_failures_total - Failed uploads (counter)
• buffer_depth_detections - Pending detections in local buffer (gauge)

---

Decision Date: 2025-12-29 Status: Approved Rationale: Addresses high-frequency detection bottleneck identified in architecture review