# MQTT Payload Migration Checklist (One Page)

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

## A. Client Implementation

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

## B. Server Migration

- [x] Add grouped v2 parser (`message/content/runtime/metadata`).
- [x] Add temporary legacy fallback parser.
- [x] Normalize both parsers into one internal server model.
- [x] Mark required fields:
  - [x] `message.client_id`
  - [x] `message.status`
  - [x] `metadata.schema_version`
  - [x] `metadata.capture.type`
- [x] Keep optional fields tolerated (`runtime.process_health`, `content.screenshot`).
- [x] Update dashboard consumers to use normalized model (not raw legacy keys).
- [x] Add migration counters:
  - [x] v2 parse success
  - [x] legacy fallback usage
  - [x] parse failures
- [x] Test compatibility matrix:
  - [x] new client -> new server
  - [x] legacy client -> new server
- [x] 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