Go MQTT Vending Backend · Lesson 18 · Capstone

Turn course knowledge into a safe backend handover

Inspect the delivered system from evidence, trace its business flows, and prepare a narrow maintenance change with a rollback plan.

🎯 One skill: explain a system you did not design🧠 Separate source evidence from assumptions🧪 Authorized staging only

❓ Start with the handover story

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?

Start with commit, dependency and deployment evidence, then authoritative contracts and end-to-end traces.

🧭 Re-establish the actual system

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.

🧠 Check the handover: What is the right starting point for a delivered MQTT 5 backend?




🔬 Trace three complete business flows

  1. HTTP command: API authorization → idempotency/command record → publication and PUBACK → device acceptance/completion → persisted result → API status.
  2. Sale report: device report identity → topic/payload validation → deduplication and transaction → MQTT acknowledgment decision → application receipt or retry.
  3. Catalog/configuration: backend revision/job → publish → device validation/application → reported revision/result → retry and stale-revision policy.

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.

🔀 Compare protocol generations by behavior

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.

🛠️ Propose one narrow maintenance change

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.

Evidence checklist

Commit/dependencies, contract source, topic and ACL ownership, command/report identities, persistence boundaries, retry/expiry rules, and process readiness.

Questions for owners

What exactly does device acknowledgment mean? How is broker persistence configured? What recovery target applies? Who rotates credentials and owns escalation?

📄 Complete handover artifact: docs/backend-handover.md

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.

🗂️ Full file contents
# 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]`

🧪 Capstone review

  1. Explain one command, one sale, and one catalog/config flow end-to-end with evidence at each boundary.
  2. Inject one staging failure and diagnose it with the Section 17 runbook.
  3. Review mixed MQTT 3.1.1/5 interoperability and list where feature loss is expected.
  4. Present one narrow change with reproduction, behavior, regression test, rollout checks, and rollback condition.
  5. Deliver a question list for facts that source and staging cannot establish.

🏁 Course completion

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.

📋 Short self-check answers
  1. Reinspect the delivered checkout and authoritative contracts before selecting APIs.
  2. A broker ACK, application result, durable business record, and physical effect are distinct evidence.
  3. Compatibility must be checked per device cohort and behavior, not inferred from the broker/client migration.

📚 Course handover checklist: COURSE.md — Section 18. Primary references: OASIS MQTT 5.0 Standard, OASIS MQTT 3.1.1 Standard, and Go command documentation.

Ask me to review a completed handover report and help separate confirmed facts from unresolved owner questions.