docs: two new tutorials — first outbox app + Kafka relay#58
Merged
Conversation
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds docs/tutorials/first-outbox-app.md, the 10-minute walk-through deferred from #56. Output blocks in the page were captured from an end-to-end run against a clean Postgres 17 container; no hand-edited expected output. Also adds the nav entry under "Getting started" (originally scheduled for Task 4) — without it, mkdocs --strict aborts on the orphan-page warning, and the spec is firm that --strict is load-bearing. The forward link to add-kafka-relay.md lands as plain text for now (target file does not exist yet); Task 3 will retarget it once that tutorial lands. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Caught during Task 2 execution. `faststream run app:app` ImportErrors without the CLI extra, so the tutorial's install line includes it; the spec outline now matches. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per the plan's Task 3 Step 7, the kill-Kafka fallback needs a disclosure that the live demo was attempted and dropped, either at the page top or folded into the callout. An HTML comment in the callout meets that bar without injecting "scar tissue" prose into the reader-facing narrative — future maintainers see the rationale, readers don't. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Caught by code-quality review: - create_schema.py redeclares MetaData/outbox_table; flag the footgun for readers who copy both files and later edit app.py. - The Step 1 uv add output shows whatever Python uv resolves; disclaim 3.13 vs 3.14 explicitly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 task
lesnik512
added a commit
that referenced
this pull request
Jun 12, 2026
chore: archive shipped planning pair from #58
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/tutorials/first-outbox-app.md— a ~10-minute walkthrough that takes a reader fromuv initto a live outbox handler printinggot order 1, with all terminal output captured from a clean execution.docs/tutorials/add-kafka-relay.md— extends Tutorial 1 to forward each outbox row to a Kafka topic via a stacked@kafka_publisherdecorator, with literal output from a Confluentcp-kafka:7.6.0single-broker KRaft setup.Getting started:nav section (after Installation and Basic usage) and adds a relay-page pointer + landing-page decision-tree cross-link.planning/active/2026-06-12-docs-tutorials-design.md./tmp/outbox-tutorial-1and/tmp/outbox-tutorial-2) and the literal terminal output is captured in-page — no hand-edited output.Task 3 Step 6 note (kill-Kafka demo)
The spec proposed a live "kill Kafka, watch the outbox retry" step. During authoring against
cp-kafka:7.6.0,aiokafka's client-side reconnect absorbed the short outage (~10s and ~20s windows) before the outbox subscriber could surface a retry log line. The spec authorized this fallback; the tutorial replaces the live step with an "At-least-once delivery" callout that explains the contract and links to the retry-strategies reference. The callout includes a maintainer note (HTML comment) documenting the attempted approach for a future contributor who wants to reintroduce a live demo.Reviewer ask
Re-walk both tutorials on a clean machine — install from scratch, spin the containers, run the app — and confirm every "you should see" block matches. That is the single highest-leverage check.
Test plan
🤖 Generated with Claude Code