infoscreen-dev/MQTT_PAYLOAD_MIGRATION_CHECKLIST.md

MQTT Payload Migration Checklist (One Page)

Use this checklist to migrate from legacy flat dashboard payload to grouped v2 payload.

A. Client Implementation

• Create branch for migration work.
• Capture one baseline message from MQTT (legacy format).
• Implement one canonical payload builder function.
• Emit grouped blocks in this order: message, content, runtime, metadata.
• Add metadata.schema_version = "2.0".
• Add metadata.producer = "simclient".
• Add metadata.published_at in UTC ISO format.
• Map capture type to metadata.capture.type (periodic, event_start, event_stop).
• Map screenshot freshness to metadata.capture.age_s.
• Keep screenshot object unchanged in semantics (filename, data, timestamp, size).
• Keep trigger behavior unchanged (periodic and triggered sends still work).
• Add publish log fields: schema version, capture type, age.
• Validate all 3 paths end-to-end:
  • periodic
  • event_start
  • event_stop

B. Server Migration

• Add grouped v2 parser (message/content/runtime/metadata).
• Add temporary legacy fallback parser.
• Normalize both parsers into one internal server model.
• Mark required fields:
  • message.client_id
  • message.status
  • metadata.schema_version
  • metadata.capture.type
• Keep optional fields tolerated (runtime.process_health, content.screenshot).
• Update dashboard consumers to use normalized model (not raw legacy keys).
• Add migration counters:
  • v2 parse success
  • legacy fallback usage
  • parse failures
• Test compatibility matrix:
  • new client -> new server
  • legacy client -> new server
• Run short soak in dev.

C. Cutover and Cleanup

• Set v2 as primary parser path on server.
• Confirm fallback usage is near zero for agreed window.
• Remove legacy parser/fallback.
• Remove client-side temporary compatibility fields (if used).
• Keep one canonical schema sample in repo.
• Close migration ticket with final validation evidence.

Quick Go/No-Go Gate

Go only if all are true:

• No parse failures in dev soak
• All 3 capture types visible in dashboard
• Screenshot payload integrity unchanged
• Metadata group present and complete