Add kafka-streams module: fraud detection topology tested with TopologyTestDriver

Similarity scoring, a 5-minute windowed count that alerts once, and a KTable blocklist join, with the Spring wiring on Spring Boot 4.1.1 and Kafka Streams 4.2.1. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01RjfyTgmERTWLqzafu34Cth
2026-10-14 06:44:56 +00:00
parent 5db56e70a0
commit 59fcdbe079
19 changed files with 520 additions and 0 deletions
@@ -0,0 +1,43 @@
+# kafka-streams
+
+Companion code for *Kafka Streams with Spring Boot 4: Real-Time Fraud Detection with Vector
+Similarity* on [ankurm.com](https://ankurm.com). The whole topology runs under
+`TopologyTestDriver`, so **no Kafka broker is needed** to run anything here.
+
+| Stack | Version |
+|---|---|
+| JDK | 25 (Temurin 25.0.4.1+1) |
+| Spring Boot | 4.1.1 |
+| Spring for Apache Kafka | 4.1.1 |
+| kafka-streams / kafka-streams-test-utils | 4.2.1 (what Boot 4.1.1 manages) |
+
+## Run it
+
+```bash
+./scripts/run-all.sh        # runs the tests, rewrites output/*.txt
+```
+
+## What is where
+
+| File | Role |
+|---|---|
+| `FraudTopology` | The topology as plain Kafka Streams code: similarity scoring, 5-minute velocity count, blocklist KTable join |
+| `Embedder` | A hand-built 6-number feature vector and cosine similarity (not a learned model) |
+| `FraudStreamsConfig` | The only Spring wiring: `@EnableKafkaStreams` plus handing the `StreamsBuilder` to the topology |
+| `FraudTopologyTest` | Five tests; each one writes the matching `output/NN-*.txt` |
+| `ContextLoadsTest` | Loads the Spring context with `auto-startup=false` to show the wiring without a broker |
+
+## Captured output
+
+Every file in `output/` is written by a test that also asserts it.
+
+| File | Shows |
+|---|---|
+| `01-similarity-scores.txt` | Scores for five sample transactions against the 0.98 threshold |
+| `02-similarity-alerts.txt` | Only the fraud-shaped transaction produces an alert |
+| `03-velocity-window.txt` | Six transactions in two minutes give one alert; the next window starts from one |
+| `04-blocklist-table-join.txt` | Join before blocking, after blocking, and after a tombstone |
+| `05-topology-description.txt` | `Topology.describe()` of the whole graph |
+| `06-spring-context.txt` | The Spring factory bean is wired and not running |
+
+The article carries the explanations; there is deliberately no `docs/` folder.