This documentation covers the Wow framework, a modern reactive CQRS/Event Sourcing microservice development framework based on Domain-Driven Design (DDD) principles. Wow enables developers to build scalable, event-driven applications in Kotlin with minimal boilerplate code through declarative design patterns and compile-time code generation.
For detailed architectural patterns and design principles, see Architecture and Core Concepts. For information on the project's modular structure, see Module Structure. To begin using the framework, see Getting Started.
Sources: gradle.properties24 README.md5-16 README.zh-CN.md5-24
Wow is a comprehensive framework that implements CQRS (Command Query Responsibility Segregation) and Event Sourcing patterns with reactive programming support. The framework provides:
The framework is built on Spring Boot and integrates with multiple storage backends including MongoDB, Redis, R2DBC databases, Elasticsearch, and Kafka.
Sources: gradle.properties24 README.md16 wow-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports1-30
The following diagram shows the main components and their relationships:
Sources: wow-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports1-30 README.md30-40
The command processing pipeline is centered on CommandGateway, which orchestrates the entire write-side flow:
The DefaultCommandGateway implementation coordinates:
BloomFilterIdempotencyChecker (default) or NoOpIdempotencyCheckerWaitStrategyRegistrar allowing clients to wait for specific processing stages (SENT, PROCESSED, PROJECTED, etc.)Sources: wow-spring-boot-starter/src/main/kotlin/me/ahoo/wow/spring/boot/starter/command/CommandGatewayAutoConfiguration.kt14-145 README.md36-40
The framework persists all state changes as immutable events:
| Component | Interface/Class | Purpose |
|---|---|---|
| Event Store | EventStore | Persist and retrieve event streams |
| Snapshot Repository | SnapshotRepository | Cache aggregate state at specific versions |
| State Event Bus | StateEventBus | Publish aggregate state changes |
| Domain Event Bus | DomainEventBus | Distribute domain events to subscribers |
Event storage is pluggable through auto-configuration classes:
MongoEventSourcingAutoConfiguration for MongoDBR2dbcAutoConfiguration for R2DBC databasesElasticsearchEventSourcingAutoConfiguration for ElasticsearchSources: wow-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports7-15 README.md94-98
The DomainEventDispatcher routes events to registered handlers:
Event processors are automatically registered via EventProcessorAutoRegistrar, which scans for:
@OnEvent annotated methods in saga classes@ProjectionProcessor annotated classes for read model updatesWow uses annotation-driven development with compile-time code generation:
| Annotation | Applied To | Purpose |
|---|---|---|
@AggregateRoot | Class | Marks a class as an aggregate root |
@OnCommand | Method | Handles incoming commands |
@OnSourcing | Method | Applies events to aggregate state |
@OnEvent | Method | Handles domain events in sagas |
@ProjectionProcessor | Class | Defines a projection for read models |
The wow-compiler module uses Kotlin Symbol Processing (KSP) to generate:
QuerySymbolProcessorMetadataSymbolProcessorSources: example/example-server/build.gradle.kts59 README.md132-208
Storage backends are selected through Spring Boot configuration properties:
Example configuration:
Sources: example/transfer/example-transfer-server/src/main/resources/application.yaml46-53 wow-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports11-16
Wow includes a built-in compensation system for handling event processing failures:
The compensation domain includes:
ExecutionFailed aggregate to track failed event processing attemptsCompensationScheduler for automatic retry with exponential backoffSources: compensation/README.md1-31 README.md300-331
Wow provides specialized testing utilities following the Given-When-Expect pattern:
| Utility | Purpose | Usage Pattern |
|---|---|---|
AggregateVerifier | Test aggregate behavior | givenOwnerId(id).whenCommand(cmd).expectEvent(evt) |
SagaVerifier | Test saga coordination | whenEvent(evt).expectCommand(cmd) |
These utilities enable achieving 80%+ test coverage without complex mocking:
Sources: README.md115-266 README.zh-CN.md109-124
The wow-spring-boot-starter module provides comprehensive auto-configuration:
| Auto-Configuration Class | Configures |
|---|---|
CommandGatewayAutoConfiguration | DefaultCommandGateway, CommandWaitNotifier |
EventSourcingAutoConfiguration | EventStore, state event bus |
EventDispatcherAutoConfiguration | DomainEventDispatcher, event function registrar |
AggregateAutoConfiguration | StateAggregateFactory, aggregate metadata |
WebFluxAutoConfiguration | Command routing, OpenAPI endpoints |
CompensationAutoConfiguration | Compensation domain components |
The starter also registers Gradle feature capabilities for optional dependencies:
mongoSupport for MongoDB integrationkafkaSupport for Kafka event busredisSupport for Redis cache and event buswebfluxSupport for reactive HTTP endpointsopentelemetrySupport for distributed tracingSources: wow-spring-boot-starter/build.gradle.kts6-47 wow-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports1-30
When webfluxSupport is enabled, Wow automatically generates reactive HTTP endpoints for commands:
The WebFluxAutoConfiguration creates:
commandRouterFunction bean for routing command requestsCommandRequestUserAgentHeaderAppender to enrich commands with HTTP headersCommandRequestRemoteIpHeaderAppender to capture client IP addressesGlobalExceptionHandler for consistent error responsesOpenAPISchemaBuilderSources: wow-spring-boot-starter/src/test/kotlin/me/ahoo/wow/spring/boot/starter/webflux/WebFluxAutoConfigurationTest.kt56-84 README.md106-113
The Wow framework is organized as a multi-module Gradle project:
| Module Category | Key Modules | Purpose |
|---|---|---|
| Core | wow-core, wow-api | Fundamental interfaces and implementations |
| Storage | wow-mongo, wow-redis, wow-r2dbc, wow-elasticsearch | Pluggable storage backends |
| Messaging | wow-kafka | Event bus implementations |
| Integration | wow-spring, wow-spring-boot-starter | Spring Boot integration |
| Tools | wow-compiler, wow-openapi, wow-test | Development utilities |
| Operations | wow-compensation-core, wow-compensation-domain | Event compensation system |
Dependency management is centralized through:
wow-dependencies BOM (Bill of Materials)gradle/libs.versions.toml version catalogFor detailed module descriptions, see Module Structure.
Sources: wow-spring-boot-starter/build.gradle.kts49-79 gradle.properties22-23
The framework has been tested under high load conditions:
| Scenario | Wait Strategy | Average TPS | Peak TPS | Avg Response Time |
|---|---|---|---|---|
| Add Cart Item | SENT | 59,625 | 82,312 | 29ms |
| Add Cart Item | PROCESSED | 18,696 | 24,141 | 239ms |
| Create Order | SENT | 47,838 | 86,200 | 217ms |
| Create Order | PROCESSED | 18,230 | 25,506 | 268ms |
The WaitStrategy allows trading latency for consistency guarantees:
SENT - Return immediately after command is sent (lowest latency)PROCESSED - Wait for aggregate to process commandPROJECTED - Wait for read models to be updated (strongest consistency)Sources: README.md42-92 README.zh-CN.md77-86
The framework source code is available at https://github.com/Ahoo-Wang/Wow under the Apache License 2.0.
Sources: gradle.properties25-29 README.md20-22
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.