AI Guide (copyable)#

You are writing code for a Spring Boot project built on soda-core (com.hibuka.soda:soda-core-base). It is a DDD + CQRS framework. Follow the conventions below. Do not invent your own style.

Architecture#

Request → Controller (adapter) → AppService (application) → BusFacade (CQRS bus)
                                                                  ↓
                                            QueryHandler / CommandHandler
                                                                  ↓
                                              Repository → DB / SLS

Core classes#

File naming#

Two hard constraints#

1. The generic must agree in three places

ListXxxQuery extends BasePageQuery<PageVO<XxxVO>>
  ⇒ QueryHandler<ListXxxQuery, PageVO<XxxVO>>
  ⇒ XxxAppService.listXxx(...) returns PageVO<XxxVO>

The R in all three must be the same type. One missing type argument, or writing XxxData where XxxVO belongs, breaks things.

2. CommandHandler must return the aggregate root

The return value of CommandHandler.handle(C) is what domain events ride on. Return void or a VO and CqrsAroundHandler has nothing to publish — the domain events are silently never sent.

// ✅ correct
public class CreatXxxCommandHandler implements CommandHandler<CreatXxxCommand, Xxx> {
    public Xxx handle(CreatXxxCommand cmd) {
        Xxx agg = Xxx.create(cmd);          // calls addPendingEvent(...) internally
        writeRepository.save(agg);           // RepositoryEventAspect publishes
        return agg;                          // ← must return
    }
}

// ❌ wrong: events never leave the process
public Void handle(CreatXxxCommand cmd) { writeRepository.save(...); return null; }

When domain events are published#

Exactly two paths. Miss one and nothing is published:

1. CommandHandler returns an aggregate root / DomainEvents / DomainEvent — CqrsAroundHandler publishes.
2. Repository's save / update / delete / operate acting on an AbstractAggregateRoot — RepositoryEventAspect publishes after the transaction commits.

Mutate the aggregate, return void, and skip *Repository persistence → no event. Aggregates must be persisted through the *Repository methods.

Configuration#

soda:
  event:
    bus-type: simple          # simple | redis, default simple
    redis:                    # only used when bus-type=redis
      stream:
        group-name: my-group
        consumer-name: my-consumer
        idempotency:
          enabled: true

# note the prefix is scoda., not soda.
scoda:
  ddd:
    cqrs:
      async:
        core-pool-size: 8
        max-pool-size: 16

Build and test#

mvn clean verify          # build + test (what releases use)
mvn test                  # tests only
mvn clean install         # install to the local repo

Java 17+, 21 recommended. Do not use the cp pom-3.2.xml pom.xml multi-POM workflow — it is deprecated; the root pom-2.3.xml / pom-2.7.xml / pom-3.2.xml files are leftovers.

Common traps#

• Handlers are matched by exact class. SimpleCommandBus / SimpleQueryBus look up handlers.get(command.getClass()) — no inheritance. A handler written for a parent class will not catch a subclass command. Each command type may have exactly one CommandHandler; a later registration overwrites the earlier one.
• **EventHandler does walk the hierarchy.** SimpleEventBus.publish looks up parent classes and interfaces, so EventHandler<DomainEvent> catches everything.
• sendMqCommand is a stub that always throws UnsupportedOperationException. Never call it.
• AbstractAggregateRoot extends AbstractDomainEvent — the aggregate root is itself an event and carries eventId / requestId fields. Historical design; nothing to assign, leave it alone.
• @AutoConfigureAfter takes string class names, not Class references (for Spring Boot 3/4 compatibility). Copy that style when adding auto-configuration.
• PreChecker is deprecated; use ParamChecker.
• EventSerializer is what keeps Jackson 2/3 compatible. If you add Jackson annotations, use the Jackson 2 coordinates com.fasterxml.jackson.annotation.*, not the Jackson 3 ones (those break on Spring Boot 4).
• knife4j-openapi3-spring-boot-starter is optional. When subclassing BaseCommand / BaseQuery / AbstractDomainEvent, the project itself must bring io.swagger.core.v3:swagger-annotations or it will not compile.

Things you must not do#

• Do not invent @Command / @Query / @Handler annotations — soda has no custom annotations at all. Everything is CommandHandler / QueryHandler / EventHandler interfaces plus @Component.
• Do not inject a repository's implementation class into the application layer; inject only the interface (otherwise the application layer depends on the infrastructure layer).
• Do not call handlers directly, bypassing BusFacade.
• Do not put business rules in a Command — that is the aggregate root's job. Commands carry business parameters only; the framework fills in the context fields.