Quickstart#

You write no code. First generate a runnable project from the generator — H2 in-memory database, schema script, and complete DDD sample code all included. Your only job is mvn spring-boot:run, then watch it work in the browser.

Once it runs, come back to Core Concepts and Write a Command — it will go much faster.

Step 1: Generate the project#

Open https://start.soda.hibuka.com, pick a template, fill in three fields, download the zip.

Pick the SODA Simple template (monolith). Choose scoda-cloud if you need a multi-module layout.

The generated project already contains:

• A complete DDD layering layout (adapter / application / domain / infrastructure)
• Full CRUD for a “Producer” aggregate: commands, queries, events, repositories
• H2 in-memory database config + the schema-h2.sql schema script
• MyBatis-Plus, Knife4j (Swagger), and unified exception handling

Step 2: Just run it#

unzip my-soda-project.zip
cd my-soda-project
mvn spring-boot:run

No MySQL to install, no Redis to install. When startup completes you'll see:

Tomcat started on port 8080

The generated project defaults to “runs out of the box”:

Step 3: Call the four endpoints#

The sample ships with a set of endpoints covering all four chains, all POST:

Create one:

curl -X POST http://localhost:8080/api/creatProducer \
  -H 'Content-Type: application/json' \
  -d '{"name": "Acme Electronics"}'

Response:

{
  "code": 200,
  "message": "",
  "data": {
    "uid": "a1b2c3d4-...",
    "name": "Acme Electronics"
  },
  "success": true
}

Query it back to confirm it really persisted:

curl -X POST http://localhost:8080/api/listProducers \
  -H 'Content-Type: application/json' \
  -d '{"pageNumber": 1, "pageSize": 10}'

You should see the record you just created in data. This step is the key one: the command chain worked, the row is in the database, and the query chain reads it back — a complete CQRS round trip.

Step 4: Look inside the database#

H2 ships a web console at http://localhost:8080/h2-console:

Click Connect and you'll see two tables on the left: scoda_producer and scoda_consumer. Run:

SELECT uid, name, gmt_create FROM scoda_producer;

Step 5: Read the code — how one command completes the journey#

This is the real point of this page. The sample code is not decoration; it plays through every soda chain once. Read the table below top to bottom and you'll understand the full lifecycle of a command.

Three places worth pausing on#

1. The event is raised by the aggregate root, not sent by a service

This line in Producer.create():

addPendingEvent(new ProducerEvent(ProducerEventTypeEnum.CREATE_PRODUCER.getDesc(), this));

addPendingEvent is protected — only the aggregate root itself can call it. A service layer trying to fire an event behind the aggregate's back won't even compile. This is the hard guarantee that “events must originate from a domain state change”.

At this point the event is only suspended, not yet published. When does it go out? After the repository save(). The RepositoryEventAspect aspect takes the suspended events and dispatches them after a successful save (after commit, if there is a transaction).

2. The domain layer doesn't know MyBatis-Plus exists

domain/producer/repository/ProducerWriteRepository.java is a pure interface extending WriteRepository<Producer>:

public interface ProducerWriteRepository extends WriteRepository<Producer> {
}

WriteRepository fixes four methods: save / update / delete / operate. The CommandHandler injects this interface, not ProducerWriteRepositoryImpl.

The implementation lives in the infrastructure layer, persisting with MyBatis-Plus. Swap in JPA, Redis, or an in-memory Map — the domain layer doesn't change.

3. Handlers need no registration

ProducerEventHandler carries @Component, and that's it — no subscribe, no registry, no XML. At startup the framework scans all EventHandlers, resolves the event type each one handles from its generics, and builds an index. The moment ProducerEvent is published, it is invoked automatically.

What the layered layout looks like#

src/main/java/com/example/soda/
├── adapter/inbound/web/         # entry: controllers, DTOs, assemblers, exception handling
├── application/                 # application layer: Command / Query / Handler / app services
│   ├── cqrs/command/
│   ├── cqrs/query/
│   ├── cqrs/handler/command/
│   ├── cqrs/handler/query/
│   └── cqrs/handler/evnet/      # event consumers (this is the template's spelling)
├── domain/                      # domain layer: aggregates, events, repository interfaces
│   ├── producer/
│   ├── consumer/
│   └── enums/
└── infrastructure/              # infrastructure: DOs, mappers, repository impls, external clients
    ├── acl/mysql/
    ├── acl/redis/
    ├── repositoryImpl/
    └── assembler/

There is only one dependency direction: adapter → application → domain, with infrastructure implementing the domain's interfaces from the other side. No Spring / MyBatis / Redis import ever appears in the domain package.

Step 6: Change one line and watch it move#

Add a log line inside ProducerEventHandler.handle():

@Override
public void handle(ProducerEvent event) throws BaseException {
    log.info("producer event received: {}, producer: {}", event.getEventType(), event.getProducer().getName());
    eventValidate(event);
}

Restart and call /api/creatProducer again. The console prints this line — proof that the event traveled from the aggregate root, through the repository, through the bus, to the consumer.

Step 7: Switch to production shape#

The sample runs on H2 + an in-process bus. Going to production means swapping two things:

soda:
  event:
    bus-type: redis
    redis:
      host: ${SODA_REDIS_HOST}
      password: ${SODA_REDIS_PASSWORD}
      stream:
        idempotency:
          enabled: true

What you now have running#

Up to this point a complete soda application is in place:

• Aggregate roots guard state changes and raise the events
• Commands run the write chain (sync + async), queries run the read chain (single + paged)
• Events are published automatically on save, and consumers receive them automatically
• Unified response envelopes Result / PageResult
• The domain layer has zero dependency on infrastructure

Next steps:

• Understand why each piece is designed this way → Request Lifecycle
• Build an aggregate root from scratch → Write a Command
• Wire in login users, tenants, requestId → Web Layer
• Deliver events across services → Event Bus & Aspect