mqtt-5-learning/teaching/lessons/0018-backend-handover.html

<!doctype html>
<html lang="en"><head>
  <meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Lesson 18 — Prepare for the MQTT 5 Backend Handover</title>
  <link rel="stylesheet" href="../assets/lesson.css"><script src="../assets/quiz.js" defer></script>
</head><body><main class="page">
  <p class="eyebrow">Go MQTT Vending Backend · Lesson 18 · Capstone</p>
  <h1>Turn course knowledge into a safe backend handover</h1>
  <p class="dek">Inspect the delivered system from evidence, trace its business flows, and prepare a narrow maintenance change with a rollback plan.</p>
  <div class="meta"><span class="pill">🎯 One skill: explain a system you did not design</span><span class="pill">🧠 Separate source evidence from assumptions</span><span class="pill">🧪 Authorized staging only</span></div>
  <section class="card callout"><p class="question">❓ Start with the handover story</p><p>You receive a new MQTT 5 backend repository. The course lab uses different topics, IDs, and packages. What must you inspect before proposing an import change or device rollout?</p><p>Start with commit, dependency and deployment evidence, then authoritative contracts and end-to-end traces.</p></section>
  <h2>🧭 Re-establish the actual system</h2>
  <p>Inspect the delivered commit, Go modules, broker configuration, deployment topology, and device contracts. Record which observations come from source, tests, broker configuration, staging, or a human owner. Do not carry lab topic names or identity assumptions into production.</p>
  <form class="card quiz" data-quiz data-correct="b" data-explanation="The delivered behavior and authoritative contracts define the migration. MQTT 3.1.1 and MQTT 5 clients are different APIs and feature support must be checked per path/device cohort." data-retry="A package import is not evidence that protocol behavior or device contracts are compatible."><p><strong>🧠 Check the handover:</strong> What is the right starting point for a delivered MQTT 5 backend?</p><label><input type="radio" name="q" value="a"> Replace the MQTT 3 import and assume the same behavior</label><br><label><input type="radio" name="q" value="b"> Reinspect exact commit, dependencies, broker, contracts, and deployment; trace behavior before proposing a change</label><br><label><input type="radio" name="q" value="c"> Reuse every topic and identity from the learning lab</label><br><button type="submit">Check answer</button><p data-feedback aria-live="polite"></p></form>
  <h2>🔬 Trace three complete business flows</h2>
  <ol><li><strong>HTTP command:</strong> API authorization → idempotency/command record → publication and PUBACK → device acceptance/completion → persisted result → API status.</li><li><strong>Sale report:</strong> device report identity → topic/payload validation → deduplication and transaction → MQTT acknowledgment decision → application receipt or retry.</li><li><strong>Catalog/configuration:</strong> backend revision/job → publish → device validation/application → reported revision/result → retry and stale-revision policy.</li></ol>
  <p>For each step, name the process and durable state owner. Record actual identifiers, topic ACLs, schema versions, timeout/expiry behavior, and evidence. If source cannot answer a question—such as physical device semantics or broker recovery targets—put it in the handover question list instead of guessing.</p>
  <h2>🔀 Compare protocol generations by behavior</h2>
  <p>Build an MQTT 3.1.1-to-5 comparison for each real flow: connection/session behavior, reason handling, expiry, properties, request/response, subscription options, acknowledgement timing, and client-library lifecycle. Mark feature support by device cohort. A legacy device may ignore or lack MQTT 5 properties; a server migration does not make the device understand them.</p>
  <h2>🛠️ Propose one narrow maintenance change</h2>
  <p>Choose a change with a reproducible symptom and bounded blast radius. Define expected behavior, regression coverage, observability, rollout checks, and rollback criteria before implementing. Use authorized staging simulators for acceptance checks; production migration or deployment is separate scope.</p>
  <div class="two-col"><article class="card"><h3>Evidence checklist</h3><p>Commit/dependencies, contract source, topic and ACL ownership, command/report identities, persistence boundaries, retry/expiry rules, and process readiness.</p></article><article class="card"><h3>Questions for owners</h3><p>What exactly does device acknowledgment mean? How is broker persistence configured? What recovery target applies? Who rotates credentials and owns escalation?</p></article></div>
  <h2>📄 Complete handover artifact: <code>docs/backend-handover.md</code></h2>
  <p>Create this report from the delivered checkout. Replace every bracket with evidence or an explicit unanswered question. It is a complete documentation artifact for this non-coding capstone; it does not prescribe Go source changes.</p>
  <details class="card" open><summary><strong>🗂️ Full file contents</strong></summary><pre><code># MQTT backend handover

## Scope and evidence

- Repository and commit: `[URL/path and commit SHA]`
- Review date and reviewer: `[date, name]`
- Runtime environments inspected: `[local, staging, production read-only, other]`
- Evidence collected: `[source paths, tests, broker config, logs, queries, owner answers]`
- Facts that remain unverified: `[list; do not infer from the learning lab]`

## Runtime map

| Process | Entry point | MQTT Client ID | Owns subscriptions/publication | Durable dependencies | Readiness evidence |
| --- | --- | --- | --- | --- | --- |
| `[role]` | `[path]` | `[identity]` | `[filters and publish classes]` | `[database/queue]` | `[endpoint or observation]` |

## Wire and identity contract

- MQTT protocol versions by device cohort: `[evidence]`
- Device identity and credential mapping: `[source/config/owner]`
- Topic namespace and ACL owner: `[evidence]`
- Payload schema versions and compatibility policy: `[evidence]`
- Correlation, idempotency, and deduplication keys: `[evidence]`
- MQTT 3.1.1 versus MQTT 5 behavior differences: `[feature, cohort, test result]`

## End-to-end traces

### HTTP command

`[authorization]` → `[durable acceptance]` → `[publish and PUBACK evidence]` → `[device acceptance]` → `[completion/result]` → `[status query]`

For each boundary, record process, stable ID, durable owner, and evidence: `[details]`.

### Sale report

`[device report ID]` → `[topic/payload validation]` → `[transaction and dedupe]` → `[MQTT acknowledgment decision]` → `[application receipt/retry]`

For each boundary, record process, stable ID, durable owner, and evidence: `[details]`.

### Catalog or configuration update

`[revision/job]` → `[publish]` → `[device validation/application]` → `[reported revision/result]` → `[stale/retry policy]`

For each boundary, record process, stable ID, durable owner, and evidence: `[details]`.

## Recovery and operations

- Session persistence, expiry, and reconnect behavior: `[evidence]`
- Database migrations and backup/restore owner: `[evidence]`
- Outbox/retry/dead-letter behavior: `[evidence]`
- Liveness and readiness meaning by process: `[evidence]`
- Failure reproduced and diagnostic path: `[symptom, IDs, evidence, layer, recovery]`
- Physical-effect ambiguity and reconciliation policy: `[evidence or owner question]`

## Proposed maintenance change

- Reproduction and observed result: `[steps and evidence]`
- Expected behavior and acceptance check: `[specific]`
- Files and wire contracts affected: `[paths; distinguish internal from device-facing change]`
- Regression coverage and staging cohort: `[checks and devices]`
- Rollout guardrails and abort signal: `[metrics/threshold/owner]`
- Rollback condition and recovery action: `[specific]`

## Questions requiring an owner

1. Device acknowledgment semantics: `[owner, answer, or unresolved]`
2. Broker persistence and recovery target: `[owner, answer, or unresolved]`
3. Credential rotation and revocation: `[owner, answer, or unresolved]`
4. Escalation and physical reconciliation: `[owner, answer, or unresolved]`

## Handover decision

- Confirmed safe maintenance scope: `[narrow change or none]`
- Explicitly excluded rollout scope: `[devices/environments/actions]`
- Evidence reviewer still needs: `[list]`
</code></pre></details>
  <h2>🧪 Capstone review</h2>
  <ol><li>Explain one command, one sale, and one catalog/config flow end-to-end with evidence at each boundary.</li><li>Inject one staging failure and diagnose it with the Section 17 runbook.</li><li>Review mixed MQTT 3.1.1/5 interoperability and list where feature loss is expected.</li><li>Present one narrow change with reproduction, behavior, regression test, rollout checks, and rollback condition.</li><li>Deliver a question list for facts that source and staging cannot establish.</li></ol>
  <div class="card"><h3>🏁 Course completion</h3><p>You are ready to maintain the delivered system when you can explain the traced flows, diagnose an injected failure, justify a small change with evidence, and distinguish confirmed behavior from unanswered operational questions. This checkpoint does not itself authorize a production rollout.</p></div>
  <details class="card"><summary><strong>📋 Short self-check answers</strong></summary><ol><li>Reinspect the delivered checkout and authoritative contracts before selecting APIs.</li><li>A broker ACK, application result, durable business record, and physical effect are distinct evidence.</li><li>Compatibility must be checked per device cohort and behavior, not inferred from the broker/client migration.</li></ol></details>
  <p>📚 Course handover checklist: <a href="../../COURSE.md#section-18--prepare-for-the-mqtt-5-backend-handover">COURSE.md — Section 18</a>. Primary references: <a href="https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html">OASIS MQTT 5.0 Standard</a>, <a href="https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html">OASIS MQTT 3.1.1 Standard</a>, and <a href="https://pkg.go.dev/cmd/go">Go command documentation</a>.</p>
  <p>Ask me to review a completed handover report and help separate confirmed facts from unresolved owner questions.</p>
  <footer><p>Previous: <a href="0017-operations-diagnostics.html">Lesson 17 — operations and diagnosis</a> · End of the course plan.</p></footer>
</main></body></html>