Wow Framework

Wow is a reactive CQRS (Command Query Responsibility Segregation) and Event Sourcing framework designed to make domain decisions explicit, testable, and traceable. It transforms every write operation into an observable domain pipeline:

HTTP Command → Aggregate Decision → Domain Event → Replayed State → Projection / Saga

When to use Wow

Use Wow when your business rules are complex and require:

• State history (Event Sourcing)
• Multiple read models (Projections)
• Cross-aggregate workflows (Sagas)

Note: For simple CRUD operations where a single database transaction suffices, the overhead of event evolution and eventual consistency may not be justified.

wow-core is the reactive runtime core of the Wow framework. It provides the public interfaces and foundational implementations for command processing, event sourcing, message dispatching, waiting stages, projections, and Sagas.

When to use wow-core directly

• When implementing a domain runtime or a non-Spring integration where you need to directly use CommandGateway, EventStore, the message bus, or the Dispatcher.
• When developing extension modules that need to hook into the Wow runtime lifecycle.

Note: For Spring Boot services, it is recommended to use wow-spring-boot-starter instead of manually assembling wow-core components.

The Query Execution Contracts implementation plan aims to fix isolation issues in Elasticsearch (ES) cursor subscriptions and handle MongoDB projection results where primary keys might be absent.

Key Architectural Changes:

• Elasticsearch: Retains request compilation and token validation but defers client-side searching to ensure each subscription triggers an independent search.
• MongoDB: Two built-in query backends share a single internal mapping function. If the primary key is present, it reuses the existing strict renaming function; if the primary key is absent, it performs a direct JSON conversion.
• Unchanged Components: Gateway, Schema, and persistence conversion logic remain unchanged.

Tech Stack:

• Kotlin, JVM 17, Reactor
• Spring Data Elasticsearch 6.1.1
• MongoDB reactive driver
• Testing: JUnit, MockK, FluentAssert, Testcontainers

The compensation module records failures in event handler functions. It allows for the re-delivery of original events via automatic scheduling or manual intervention.

Important Constraints:

• It does not roll back databases.
• It does not undo already committed events.
• It does not automatically generate reverse business operations (compensating transactions).

Users must ensure that business handlers are idempotent and can handle side effects (like payments or notifications) that may have already occurred before a retry.

Wow is a reactive CQRS (Command Query Responsibility Segregation) and Event Sourcing framework designed for Kotlin and Java. It formalizes business logic into a specific execution flow:

Command → Aggregate decision → Domain event → Sourced state

Instead of traditional CRUD, Wow focuses on making business intent explicit through commands and preserving state changes through persisted events. This allows projections, sagas, and other processors to react to the event stream. It is suitable for both microservices and modular monoliths where rich domain rules and state history are required.

This example demonstrates how to implement account business logic using Java Aggregates and coordinate cross-account transfers using a Wow stateless Saga.

Workflow

• Success Path: Prepared -> Entry -> AmountEntered -> Confirm.
• Compensation Path (Failure): If the target account is frozen, the system executes EntryFailed -> UnlockAmount to return the locked amount to the source account.

Note: This is an event-driven compensation mechanism, not a cross-aggregate database transaction.

Module Structure

This documentation provides profiling evidence for the MongoDB and Redis execution paths during a fresh aggregate command through PROCESSED. It is used to identify optimization candidates following the merge of the SENT fast path.

Note: The throughput values provided here are for diagnostic purposes only. For official throughput evidence, refer to the paired A/B test package: ../2026-07-24-command-wait-sent-paired-ab.