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:

```text
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:

```bash
mvn install
```

The demo `pom.xml` will then depend on:

```xml
<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:

```bash
mvn install
```

From the demo project:

```bash
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.