Spring-Boot-Starter

wow-spring-boot-starter is the Spring Boot wiring entry point: it binds wow.*, registers core beans, collects RuntimeComponents, and lets one WowRuntimeLifecycle own startup and shutdown. It does not choose the application's broker, storage, security, or exporter.

Installation

implementation("me.ahoo.wow:wow-spring-boot-starter")

The base dependency provides core/spring/schema/compensation and Spring WebFlux/Jackson baselines. Kafka, Mongo, Redis, Elasticsearch, OpenTelemetry, OpenAPI, and CoSec remain optional capabilities. Starter alone with default kafka/mongo selections does not prove those implementations are present.

Auto-Configuration Mechanism

Spring Boot loads Wow entries from AutoConfiguration.imports. @ConditionalOnClass, @ConditionalOnProperty, storage/bus selections, and @ConditionalOnMissingBean then decide beans. Actual beans, routes, and runtime components after startup are the wiring evidence.

Gradle Feature Variants

Capability	Main direct capability
mongo-support	wow-mongo + reactive Mongo starter
redis-support	wow-redis + reactive Redis starter
mock-support	wow-mock
kafka-support	wow-kafka
webflux-support	wow-bi API + wow-webflux
elasticsearch-support	wow-elasticsearch + Spring Data Elasticsearch
opentelemetry-support	wow-opentelemetry
openapi-support	wow-bi API + wow-openapi + springdoc common
cosec-support	wow-cosec

Request the full coordinate, for example requireCapability("me.ahoo.wow:mongo-support"). Maven does not resolve Gradle feature variants, so it needs explicit module dependencies.

Auto-Configuration Classes

Core configuration is split across serialization, command, event, event sourcing, query, projection, Saga, metrics, and runtime lifecycle. Extension configurations join under classpath and selection conditions. Do not infer defaults from class names; inspect class and bean conditions.

Complete Configuration Properties

Use Core configuration and extension pages for the full key/default catalog. This page keeps only minimum startup boundaries to avoid copying a drifting table.

Core Configuration (wow.*)

Defaults are wow.enabled=true, wow.shutdown-timeout=60s, and wow.shutdown-quiet-period=1s. When wow.context-name is absent, spring.application.name is required; if both are absent, current bounded-context creation fails.

Command Configuration (wow.command.*)

The bus defaults to kafka, local-first to enabled, and idempotency to enabled. Without Kafka capability, explicitly select in_memory, redis, or an application implementation.

Event Configuration (wow.event.*)

The domain-event bus defaults to kafka, with local-first enabled. Its selection is independent from the state-event bus; changing one key is not enough.

Event Sourcing Configuration (wow.eventsourcing.*)

EventStore and SnapshotStore default to mongo, while the state bus defaults to kafka. Storage routing builds a primary router from named bindings. An ordinary same-type bean does not automatically replace an enabled storage capability.

Bean Wiring and Overrides

Replace only extension points whose source declares @ConditionalOnMissingBean. WowRuntime must be the only singleton named wowRuntime in the current context and have one exclusive WowRuntimeLifecycle. A competing Spring Lifecycle, DisposableBean, destroy method, or AutoCloseable.close owner fails fast to prevent double shutdown.

Starter preserves backend-native semantics: Kafka offsets, Mongo unique indexes, Redis Lua, and Elasticsearch mappings remain owned by their adapters/backends instead of duplicate core validation.

Multi-Module Project Configuration

Separating API, domain, and server keeps dependencies directed; only the server requests runtime capabilities.

Project Structure

order-api -> order-domain -> order-server

API Module Configuration

api("me.ahoo.wow:wow-api")

Domain Module Configuration

implementation("me.ahoo.wow:wow-core")
ksp("me.ahoo.wow:wow-compiler")
testImplementation("me.ahoo.wow:wow-test")

Server Module Configuration

A local candidate without external infrastructure can request mock-support and webflux-support:

implementation("me.ahoo.wow:wow-spring-boot-starter") {
    capabilities { requireCapability("me.ahoo.wow:mock-support") }
}
implementation("me.ahoo.wow:wow-spring-boot-starter") {
    capabilities { requireCapability("me.ahoo.wow:webflux-support") }
}

spring:
  application:
    name: order-service
wow:
  command:
    bus:
      type: in_memory
  event:
    bus:
      type: in_memory
  eventsourcing:
    store:
      storage: in_memory
    snapshot:
      storage: in_memory
    state:
      bus:
        type: in_memory

mock-support is for local/test use and is not production persistence evidence.

Metadata Loading

KSP generates META-INF/wow-metadata.json; MetadataSearcher lazily merges all resources with that name from the classpath. Missing generated resources leave aggregates, processors, routes, or schemas incomplete. Starter does not reconstruct the full contract through reflection.

Processor Registration

Aggregates, Sagas, and projections come from compiler metadata plus Spring bean discovery. An annotation does not form complete runtime registration when the server does not depend on the module, KSP did not run, or generated resources were not packaged.

Aggregate Processor

Aggregate command handling uses aggregate metadata and state factories. Verify with a real command and state read, not bean count alone.

Saga Processor

A Saga also needs an event-bus subscription and a started runtime component. Class presence does not prove message consumption.

Projection Processor

A projection likewise needs event subscription, processor discovery, and its target read model. Startup logs do not prove projection catch-up.

Complete Configuration Example

Build production configuration from the selected capability pages instead of copying an “everything” example. At minimum, explicitly declare context, all three buses, event/snapshot storage, and the corresponding Spring backend connections.

Best Practices

• Request only used capabilities and select buses/stores explicitly.
• Verify wiring through auto-configuration conditions, actual beans, OpenAPI, and runtime state.
• Preserve single ownership of WowRuntimeLifecycle.
• Leave backend checks to adapters/backends and public-contract validation at boundaries.

Verified failures include missing context name, a missing selected backend bean, duplicate runtime/lifecycle ownership, non-singleton runtime components, and invalid extension properties. Focused check:

./gradlew :wow-spring-boot-starter:check

Next, read Existing project and Module dependencies.