Modules

Spring DDD ships as focused Gradle modules under the group de.dwittkoetter. Most applications need only the full-stack bundle spring-ddd-starter-jpa, which bundles all the building-block modules together. Individual modules are listed here for reference; select them directly only when you need fine-grained control over what is activated.

Add a module as a Gradle dependency using:

implementation("de.dwittkoetter:<artifact>:0.0.1-SNAPSHOT")

Core libraries

Module Kind Purpose

spring-ddd-annotations

library

Framework meta-annotations and DDD stereotypes (@EventSourced, @QueryHandler, etc.) aligned with jMolecules.

spring-ddd-messaging

library

The storage-agnostic messaging core: message type annotations (@Message, @Command, @DomainEvent) and core type detection; the topic contracts a consumer reads a topic through, and compaction as a capability of a keyed topic; event serialization, upcasting and the per-topic codec that turns a domain event into a stored one and back; message metadata; the high-water mark a topic is read up to; the partition-count configuration the event store stamps each appended event’s partition key with; and the topic consumer runtime — the topic consumer factory, position-order draining, the partition lease a consumer runs under on one instance at a time, the consumers' retry budgets and their scheduler and executor, and an in-memory checkpoint store.

spring-ddd-jdbc

library

JDBC plumbing the framework’s JDBC modules share: writes that commit whatever the pool’s auto-commit setting, the schema-creation setting, and the database clock every lease is judged on.

spring-ddd-messaging-topic-jdbc

library

Relational topic storage, written in the writer’s transaction: the capture topic and its tables, the high-water-mark store and its detector, the partition-count table shared with the event store, and the table compacting topics record their progress in, across the five supported databases.

spring-ddd-messaging-consumer-jdbc

library

Relational consumer state, written in the consumer’s transaction: the consumer checkpoint store, the undelivered messages, the partition ownership and membership stores, their tables across the five supported databases, and the check that the transaction manager covers the checkpoint table’s DataSource.

spring-ddd-converter

library

Scalar type conversion: Jackson serialization and Spring type converters for wrapped value objects.

spring-ddd-domain-events

library

@DomainEventHandler runtime — framework-owned async after-commit event dispatch.

Event Sourcing

Module Kind Purpose

spring-ddd-eventsourcing

library

Event-sourcing core: @EventSourced aggregates, EventStore and SnapshotStore SPIs, aggregate loading and reconstruction.

spring-ddd-eventsourcing-jdbc

library

JDBC implementations of EventStore and SnapshotStore; 6-dialect DDL generation; @EventTable support.

CQRS

Module Kind Purpose

spring-ddd-cqrs

library

Command and query buses, the projection annotations (@InMemoryProjection, @ProjectionListener, @AdHocProjection, @ReadModelKey, …) and the in-memory read-model store behind @InMemoryProjection. The projection settings are validated with Jakarta Bean Validation, so an application depending on this library directly needs a provider such as Hibernate Validator on its classpath; the starter brings one. It runs every registered projection once a topic consumer factory is configured, as spring-ddd-starter-messaging-consumer-jdbc does; with projections registered and no factory configured, startup fails naming them.

spring-ddd-cqrs-jdbc

library

The JDBC read-model topic of every persistent projection with listeners, shared by the query and the JPA read-model stores: its tables, their DDL per dialect, and their configuration. spring-ddd-cqrs-jdbc-query and spring-ddd-starter-cqrs-jpa include it.

spring-ddd-cqrs-jdbc-query

library

Experimental. The @QueryProjection and @QueryField annotations, the read-model store behind @QueryProjection, and the repositories that query it.

spring-ddd-cqrs-jpa

library

JPA aggregate command handling (AbstractAggregateRootEntity), the @JpaProjection annotation and the read-model store behind it, which keeps each read model as an entity of the application’s own.

Saga

Module Kind Purpose

spring-ddd-saga

library

Process-manager / saga core: @Saga, @SagaEventHandler, SagaStore SPI, and deadline SPI.

spring-ddd-saga-jdbc

library

JDBC implementations of SagaStore, and deadline store; @SagaTable support.

Bridges

Module Kind Purpose

spring-ddd-starter-bridge

starter

Connects two areas when both are on the classpath: command handlers on event-sourced aggregates (CQRS + event sourcing) and commands sent from sagas (sagas + CQRS). The CQRS, event-sourcing and saga starters bring it; an application never declares it.

Spring Modulith

Module Kind Purpose

spring-ddd-domain-events-modulith

library

Spring Modulith Event Publication Registry integration: @DomainEventHandler delivery and sagas through the registry, and durable event-publication metadata restored on resubmission. Ships no transport for event routes.

Full-stack bundles

These two starters are the recommended entry point for most applications. See Starters for guidance on which to pick.

Module Kind Purpose

spring-ddd-starter-jdbc

starter

Experimental. Full-stack JDBC bundle — activates event sourcing, CQRS, sagas, bridges, and @DomainEventHandler in a single dependency; its CQRS part is the experimental spring-ddd-starter-cqrs-jdbc-query.

spring-ddd-starter-jpa

starter

Full-stack JPA bundle — activates event sourcing, CQRS with JPA aggregates, sagas, bridges, and @DomainEventHandler in a single dependency.

Framework starters

Module Kind Purpose

spring-ddd-starter-messaging-topic-jdbc

starter

Activates the topic storage on JDBC — the capture topic and its tables, the high-water-mark store and its detector — with the consumer runtime’s scheduler and executor, gated by spring.ddd.messaging.enabled, and the storage-agnostic encoding wiring — the event-type registry, the upcaster and downcaster chains, and the factory every topic builds its codec from — independent of that property. The capture topic’s retention needs a checkpoint store, which spring-ddd-starter-messaging-consumer-jdbc provides.

spring-ddd-starter-messaging-consumer-jdbc

starter

Activates the consumer state on JDBC — the checkpoint store, the undelivered messages, the partition ownership and membership stores and their tables — with the consumer runtime: the topic consumer factory, its scheduler and executor, gated by spring.ddd.messaging.enabled; and the encoding wiring, independent of that property.

spring-ddd-starter-eventsourcing-jdbc

starter

Activates event-sourcing JDBC infrastructure: event store, snapshot store, and schema initializers.

spring-ddd-starter-cqrs-jdbc-query

starter

Experimental. Bundles spring-ddd-cqrs-jdbc-query with the bare CQRS starter and both messaging JDBC starters, and auto-configures the @QueryProjection store and the read-model topics.

spring-ddd-starter-cqrs-jpa

starter

Activates the JPA aggregate command-handler infrastructure and the read-model topics of JPA projections.

spring-ddd-starter-cqrs

starter

Bare CQRS command and query buses — no persistence layer. This is the standalone command/query path for applications that do not use a relational store. It is intentionally omitted from Starters: every CQRS starter includes it.

spring-ddd-starter-saga-jdbc

starter

Activates saga persistence, scheduled deadline delivery, the capture topic and the consumer runtime that delivers events to sagas.

spring-ddd-starter-domain-events

starter

Activates the @DomainEventHandler dispatch runtime.

spring-ddd-starter-domain-events-modulith-jdbc

starter

Activates the Spring Modulith Event Publication Registry integration: registry-driven @DomainEventHandler and saga delivery, and the JDBC store for durable event-publication metadata.

Test support

Module Kind Purpose

spring-ddd-starter-test

test starter

Every Spring DDD test module as one testImplementation dependency. It adds test classes only: the areas they test come from the application’s own dependencies.

spring-ddd-cqrs-test

test

Test support for projections: ProjectionAwait, which waits until a projection has applied everything a test committed, then lets it assert once on the projection’s read models.

spring-ddd-saga-test

test

Test support for sagas: SagaAwait, which retries a check of one saga instance until it passes, and fails at once when the saga type’s consumer cannot read on.

spring-ddd-eventsourcing-test

test

Test DSLs for event sourcing: given/when/then over aggregates without a running store, and upcaster, snapshot-upcaster and downcaster tests.

spring-ddd-jdbc-test

test

Test support for relational stores: the @EnableDatabaseCleanup cleanup extension.

Observability

Module Kind Purpose

spring-ddd-observability

library

The endpoints, health indicators and metrics, without auto-configuration. Applications depend on the starter, not on this module.

spring-ddd-starter-observability

add-on starter

Actuator endpoints, health indicators and metrics for the event store, consumers, topics and sagas, and trace propagation through messages; each section appears with the part it observes: the event store, the consumer runtime (consumers and topics), the JDBC saga store, and trace propagation with spring.ddd.trace.propagate=true. See Observability.

Internal

These modules are internal to the Spring DDD build. Do not declare them as application dependencies.

Module Kind Purpose

spring-ddd-e2e

internal

Internal end-to-end test harness. Not a user dependency.

Choosing a starter

For most applications, the entry point is one of the two full-stack bundles. See Starters for the authoritative how-to, including a decision guide.

The table below shows exactly which modules each full-stack bundle aggregates, as declared in their build.gradle.kts files.

Included module spring-ddd-starter-jdbc spring-ddd-starter-jpa

spring-ddd-starter-eventsourcing-jdbc

✓

✓

spring-ddd-starter-cqrs-jdbc-query

✓

—

spring-ddd-starter-cqrs-jpa

—

✓

spring-ddd-starter-saga-jdbc

✓

✓

spring-ddd-starter-domain-events

✓

✓

Related pages