# Kafka by Investigation
### A Hands-on Course for Java Developers

A self-paced course that teaches Kafka the way production actually hands it
to you: as a situation with symptoms. You **predict** what will happen, run a
**small, bounded experiment** on a real Kafka cluster on your own machine,
**observe** the output, and only then read the explanation. Solutions are kept
in a separate folder so every experiment stays yours until you choose to
peek.

**Audience:** developers comfortable with Java and basic Spring Boot who are
new to Kafka — or who have inherited a Kafka system and want the guarantees
down cold before touching another consumer config.

**Estimated time:** 4–5 hours of hands-on work (a focused half-day), plus
reading. Per-exercise estimates are in `COURSE-GUIDE.md`.

**By the end you will be able to:**

- Explain topics, partitions, keys and offsets precisely.
- Produce and consume events using both the Kafka CLI and Java.
- Explain how a consumer group shares partitions and what a rebalance does.
- Diagnose duplicate delivery and explain the role of idempotency.
- Configure and observe Spring Kafka retries and a dead-letter topic (both
  blocking and non-blocking).
- Gather evidence from logs and commands *before* changing configuration —
  the habit this course exists to build.

**Honesty about verification:** every exercise in this pack was actually run,
end to end, and its observed output is recorded in `VERIFICATION.md`
(verified 2026-11-21). Where something could not be verified in our
environment it is labeled UNVERIFIED with the reason — nothing in this pack
claims a run that did not happen.

## What's in the pack

| File | What it is |
|---|---|
| `COURSE-GUIDE.md` | The learning path, outcomes, and suggested pacing |
| `PREREQUISITES.md` | What you need installed, with tested versions |
| `SETUP.md` | Standing the lab cluster up (and stopping it safely) |
| `exercises/01…05` | Five investigations, prediction-first |
| `solutions/01…05` | Full walkthroughs with observed output — **read after attempting** |
| `agent-guide/AGENTS.md` | Rules for coding agents (Claude Code, Codex, etc.) helping you |
| `agent-guide/PROMPTS.md` | Copy-paste prompts for hint-first tutoring |
| `TROUBLESHOOTING.md` | The errors you are most likely to meet |
| `VERIFICATION.md` | The evidence ledger: what we ran, what we saw, when |
| `LICENSE-NOTICE.md` | Licensing of this pack and its references |

## Requirements (short version)

- Docker (running locally; verified with a Linux Docker host)
- JDK 25 and Maven (the course repo ships `./mvnw`) for the Java exercises
- The **kafka-lab** repository — the lab environment this course drives
  (exact paths in `PREREQUISITES.md`)

Everything runs on your machine. Nothing connects to a cloud service, and no
exercise produces more than a few hundred records.

## How to start

1. Read `PREREQUISITES.md`, then `SETUP.md` — the cluster takes ~1 minute.
2. Open `COURSE-GUIDE.md` and start at Exercise 01.
3. Work in order: each exercise assumes the previous one's vocabulary.
4. **Write your prediction before running any command.** The solution file
   linked at the bottom of each exercise is only honest if your prediction
   exists first.

## Pausing and cleaning up

`docker compose -f docker/docker-compose.yml stop` pauses the lab with all
data intact — resume with `start`. The destructive reset (deletes all
records and offsets) is documented in `SETUP.md` behind an explicit warning;
you never need it to finish the course.

## A note on what this is

This is an educational product. It teaches concepts and diagnostic habits;
it is not a certification, an exam, or a job guarantee, and completing it
does not qualify you for anything beyond knowing what it says you know. The
commands and behaviors described here were verified against Apache Kafka
3.9.0 and Spring Kafka 3.3.10 on the date above; Kafka moves, so treat the
official documentation (linked throughout) as the final word when versions
differ.
