redis-stream-springboot-starter/docs/superpowers/specs/2026-06-25-redis-stream-demo-design.md

Redis Stream Starter Demo Design

Goal

Create an independent Spring Boot demo project at C:\code\hatch\redis-stream-starter-demo that imports the local redis-stream-springboot-starter and verifies Redis Stream message publish and subscribe behavior against the provided Redis service.

Context

The current repository is a Maven single-module Spring Boot starter:

• Group/artifact/version: com.njcn:redis-stream-springboot-starter:1.0.0-SNAPSHOT
• Spring Boot baseline: 2.3.12.RELEASE
• Java baseline: 8
• Auto-configuration entry: META-INF/spring.factories
• Producer API: RedisStreamEnhanceTemplate#send(topic, message, compress)
• Consumer API: subclass EnhanceStreamConsumerHandler<T>

Demo Project Location

The demo project will be created outside this repository at:

C:\code\hatch\redis-stream-starter-demo

This keeps the starter repository unchanged except for this design document and allows the demo to behave like a real downstream application.

Dependency Flow

Before building the demo, install the starter into the local Maven repository:

mvn install

The demo pom.xml will then depend on:

<dependency>
    <groupId>com.njcn</groupId>
    <artifactId>redis-stream-springboot-starter</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

The demo will use Spring Boot 2.3.12.RELEASE to match the starter's dependency baseline.

Redis Configuration

The demo will use the provided Redis Stream service:

• Host: configured as 192.168.1.22
• Port: configured as 12379
• Password: configured in the local demo application config, not copied into this design document

The demo should allow overriding these values with environment variables or JVM system properties so the sample remains reusable.

Runtime Components

The demo will include:

• DemoApplication: Spring Boot entry point.
• DemoMessage: message payload extending StreamBaseMessage.
• DemoProducer: injects RedisStreamEnhanceTemplate and publishes a message.
• DemoConsumer: extends EnhanceStreamConsumerHandler<DemoMessage> and subscribes to the same topic and group.
• DemoStartupRunner: sends one message after the application starts and logs the returned Redis RecordId.

The consumer will log received message content and store consumed messages in an in-memory queue for integration test assertions.

Message Flow

1. Application starts and auto-configuration creates the starter beans.
2. DemoStartupRunner creates a DemoMessage.
3. DemoProducer calls RedisStreamEnhanceTemplate#send("demo-topic", message, false).
4. The starter writes the message to Redis Stream with XADD.
5. The starter listener reads the message through XREADGROUP.
6. DemoConsumer#handleMessage receives the deserialized DemoMessage.
7. The starter ACKs the message after successful handling.

Testing

Add an integration test that:

• Starts the demo Spring context.
• Uses the real Redis service when reachable.
• Sends a unique test message.
• Waits for the consumer to receive it.
• Asserts that the received message payload and key match the sent message.

If Redis is unreachable, the integration test should be skipped instead of failed. This keeps local builds deterministic while still validating the real publish/subscribe flow when the service is available.

Error Handling

The demo consumer will return false for isRetry() so test failures are surfaced through assertions instead of retry loops. Unexpected handler exceptions will be logged by the starter path and ACKed according to the existing handler behavior.

Verification Commands

From the starter repository:

mvn install

From the demo project:

mvn test
mvn spring-boot:run

Out of Scope

• Publishing the starter to Nexus.
• Changing starter production code.
• Adding Docker or Testcontainers.
• Building a UI or HTTP API for the demo.