Split event sourcing and application code. Fix #8

Author: eugene-khyst

README.md

@@ -25,13 +25,17 @@
     - [Database polling alternative](#4-7-3)
   - [Adding new asynchronous event handlers](#4-8)
   - [Drawbacks](#4-9)
-  - [Class diagrams](#4-10)
-    - [Class diagram of the domain model](#4-10-1)
-    - [Class diagram of the projections](#4-10-2)
-    - [Class diagram of the service layer](#4-10-3)
-- [How to run the sample?](#5)
-
-<!-- Table of contents is made with https://github.com/evgeniy-khist/markdown-toc -->
+- [Project structure](#5)
+  - [Gradle subprojects](#5-1)
+  - [Database schema migrations](#5-2)
+  - [Class diagrams](#5-3)
+    - [Class diagram of the domain model](#5-3-1)
+    - [Class diagram of the projections](#5-3-2)
+    - [Class diagram of the service layer](#5-3-3)
+- [How to adapt it to your domain?](#6)
+- [How to run the sample?](#7)
+
+<!-- Table of contents is made with https://github.com/eugene-khyst/md-toc-cli -->
 
 ## <a id="1"></a>Introduction
 
@@ -62,16 +66,17 @@ But PostgreSQL, the world's most advanced open-source database, is also suitable
 You can use PostgreSQL as an event store without additional frameworks or extensions
 instead of setting up and maintaining a separate specialized database for event sourcing.
 
-This repository provides a reference implementation of an event-sourced system that uses PostgreSQL as an event store.
-You can also [fork](https://github.com/evgeniy-khist/postgresql-event-sourcing/fork) the repo
-and use it as a template for your projects.
+This repository provides a reference implementation of an event-sourced system 
+that uses PostgreSQL as an event store built with Spring Boot.
+[Fork](https://github.com/eugene-khyst/postgresql-event-sourcing/fork) the repository and use it as a template for your projects.
+Or clone the repository and run end-to-end tests to see how everything works together.
 
 ![PostgreSQL Logo](img/potgresql-logo.png)
 
 See also
 
-* [Event Sourcing with EventStoreDB](https://github.com/evgeniy-khist/eventstoredb-event-sourcing)
-* [Event Sourcing with Kafka and ksqlDB](https://github.com/evgeniy-khist/ksqldb-event-souring)
+* [Event Sourcing with EventStoreDB](https://github.com/eugene-khyst/eventstoredb-event-sourcing)
+* [Event Sourcing with Kafka and ksqlDB](https://github.com/eugene-khyst/ksqldb-event-souring)
 
 ## <a id="2"></a>Example domain
 
@@ -483,7 +488,7 @@ This mechanism is used by default as more efficient.
 After restarting the backend, existing subscriptions will only process new events after the last processed event 
 and not everything from the first one.
 
-> [!WARNING]  
+> **WARNING**  
 > Critical content demanding immediate user attention due to potential risks.
 New subscriptions (event handlers) in the first poll will read and process all events.
 Be careful, if there are too many events, they may take a long time to process.
@@ -508,43 +513,72 @@ Using PostgreSQL as an event store has a lot of advantages, but there are also d
    and events created by all later transactions will be read by the event subscription processor 
    only after this long-running transaction is committed.
 
-### <a id="4-10"></a>Class diagrams
+## <a id="5"></a>Project structure
+
+### <a id="5-1"></a>Gradle subprojects
 
 This reference implementation can be easily extended to comply with your domain model.
 
-#### <a id="4-10-1"></a>Class diagram of the domain model
+Event sourcing related code and application specific code are located in separate Gradle subprojects:
+* [`postgresql-event-sourcing-core`](postgresql-event-sourcing-core): event sourcing and PostgreSQL related code, a shared library, `eventsourcing.postgresql` package,
+* [`event-sourcing-app`](event-sourcing-app): application specific code, a simplified ride-hailing sample, `com.example.eventsourcing` package.
+
+`event-sourcing-app` depends on `postgresql-event-sourcing-core`:
+```groovy
+dependencies {
+    implementation project(':postgresql-event-sourcing-core')
+}
+```
+
+### <a id="5-2"></a>Database schema migrations
+
+Event sourcing related database schema migrations:
+* [V1__eventsourcing_tables.sql](event-sourcing-app/src/main/resources/db/migration/V1__eventsourcing_tables.sql)
+* [V2__notify_trigger.sql](event-sourcing-app/src/main/resources/db/migration/V2__notify_trigger.sql)
+
+Application specific projections database schema migration:
+* [V3__projection_tables.sql](event-sourcing-app/src/main/resources/db/migration/V3__projection_tables.sql)
+
+### <a id="5-3"></a>Class diagrams
+
+#### <a id="5-3-1"></a>Class diagram of the domain model
 
 ![Class diagram of the domain model](img/class-domain.svg)
 
-#### <a id="4-10-2"></a>Class diagram of the projections
+#### <a id="5-3-2"></a>Class diagram of the projections
 
 ![Class diagram of the projections](img/class-projection.svg)
 
-#### <a id="4-10-3"></a>Class diagram of the service layer
+#### <a id="5-3-3"></a>Class diagram of the service layer
 
 ![Class diagram of the service layer](img/class-service.svg)
 
-## <a id="5"></a>How to run the sample?
+## <a id="6"></a>How to adapt it to your domain?
+
+To adapt this sample to your domain model, make changes to `event-sourcing-app` subproject.
+No changes to `postgresql-event-sourcing-core` subproject are required.
+
+## <a id="7"></a>How to run the sample?
 
 1. Download & install [SDKMAN!](https://sdkman.io/install).
 
-2. Install JDK 17
+2. Install JDK 21
     ```bash
     sdk list java
-    sdk install java 17.0.x-tem
+    sdk install java 21-tem
     ```
 
 3. Install [Docker](https://docs.docker.com/engine/install/)
    and [Docker Compose](https://docs.docker.com/compose/install/).
 
 4. Build Java project and Docker image
     ```bash
-    ./gradlew clean build bootBuildImage -i
+    ./gradlew clean build jibDockerBuild -i
     ```
 
 5. Run PostgreSQL, Kafka and event-sourcing-app
     ```bash
-    docker compose up -d --scale event-sourcing-app=2
+    docker compose --env-file gradle.properties up -d --scale event-sourcing-app=2
     # wait a few minutes
     ```
 

build.gradle

@@ -1,61 +1,16 @@
-plugins {
-    id 'java'
-    id 'org.springframework.boot' version '3.0.4'
-    id 'io.spring.dependency-management' version '1.1.0'
+allprojects {
+    group = 'com.example'
+    version = project.properties['project_version']
 }
 
-group = 'com.example'
-version = '2.0.0'
-sourceCompatibility = '17'
+subprojects {
+    apply plugin: 'java'
 
-repositories {
-    mavenCentral()
-}
-
-configurations {
-    compileOnly {
-        extendsFrom annotationProcessor
+    java {
+        sourceCompatibility = '21'
     }
-}
-
-ext {
-    set('postgresql_version', '42.5.4')
-    set('mapstruct_version', '1.5.3.Final')
-    set('lombok_mapstruct_binding_version', '0.2.0')
-    set('testcontainers_version', '1.17.6')
-}
-
-dependencies {
-    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
-    implementation 'org.springframework.boot:spring-boot-starter-web'
-    implementation 'org.springframework.boot:spring-boot-starter-validation'
-    implementation 'org.springframework.kafka:spring-kafka'
-
-    implementation "org.postgresql:postgresql:${postgresql_version}"
-    implementation "org.mapstruct:mapstruct:${mapstruct_version}"
 
-    implementation 'org.flywaydb:flyway-core'
-
-    compileOnly 'org.projectlombok:lombok'
-    annotationProcessor 'org.projectlombok:lombok'
-    annotationProcessor "org.projectlombok:lombok-mapstruct-binding:${lombok_mapstruct_binding_version}"
-    annotationProcessor "org.mapstruct:mapstruct-processor:${mapstruct_version}"
-
-    testCompileOnly 'org.projectlombok:lombok'
-    testAnnotationProcessor 'org.projectlombok:lombok'
-    testImplementation 'org.springframework.boot:spring-boot-starter-test'
-    testImplementation 'org.springframework.kafka:spring-kafka-test'
-    testImplementation 'org.testcontainers:junit-jupiter'
-    testImplementation 'org.testcontainers:postgresql'
-    testImplementation 'org.testcontainers:kafka'
-}
-
-dependencyManagement {
-    imports {
-        mavenBom "org.testcontainers:testcontainers-bom:${testcontainers_version}"
+    repositories {
+        mavenCentral()
     }
-}
-
-test {
-    useJUnitPlatform()
-}
+}

docker-compose.yml

@@ -30,9 +30,9 @@ services:
         condition: service_healthy
 
   kafka:
-    image: confluentinc/cp-kafka:7.3.2
+    image: confluentinc/cp-kafka:7.5.1
     environment:
-      KAFKA_BROKER_ID: 1
+      KAFKA_NODE_ID: 1
       KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT'
       KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092'
       KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
@@ -42,19 +42,19 @@ services:
       KAFKA_JMX_PORT: 9101
       KAFKA_JMX_HOSTNAME: localhost
       KAFKA_PROCESS_ROLES: 'broker,controller'
-      KAFKA_NODE_ID: 1
       KAFKA_CONTROLLER_QUORUM_VOTERS: '1@kafka:29093'
       KAFKA_LISTENERS: 'PLAINTEXT://kafka:29092,CONTROLLER://kafka:29093,PLAINTEXT_HOST://0.0.0.0:9092'
       KAFKA_INTER_BROKER_LISTENER_NAME: 'PLAINTEXT'
       KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
       KAFKA_LOG_DIRS: '/tmp/kraft-combined-logs'
+      # Replace CLUSTER_ID with a unique base64 UUID using "bin/kafka-storage.sh random-uuid"
+      # See https://docs.confluent.io/kafka/operations-tools/kafka-tools.html#kafka-storage-sh
+      CLUSTER_ID: 'MkU3OEVBNTcwNTJENDM2Qk'
     ports:
       - "9092:9092"
       - "9101:9101"
     volumes:
       - kafka-data:/var/lib/kafka/data
-      - ./kafka/update_run.sh:/tmp/update_run.sh
-    command: "bash -c 'if [ ! -f /tmp/update_run.sh ]; then echo \"ERROR: Did you forget the update_run.sh file that came with this docker-compose.yml file?\" && exit 1 ; else /tmp/update_run.sh && /etc/confluent/docker/run ; fi'"
     healthcheck:
       test: [ "CMD", "nc", "-z", "localhost", "9092" ]
       start_period: 15s
@@ -63,14 +63,14 @@ services:
       retries: 5
 
   nginx:
-    image: nginx:1.23-alpine
+    image: nginx:1.25-alpine
     ports:
       - "8080:80"
     volumes:
       - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
 
   event-sourcing-app:
-    image: evgeniy-khyst/postgresql-event-sourcing:2.0.0
+    image: eugene-khyst/postgresql-event-sourcing:${project_version}
     environment:
       SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/postgres
       SPRING_DATASOURCE_USERNAME: admin

event-sourcing-app/build.gradle

@@ -0,0 +1,52 @@
+plugins {
+    id 'org.springframework.boot' version "${spring_boot_version}"
+    id 'io.spring.dependency-management' version "${spring_dependency_management_version}"
+    id 'com.google.cloud.tools.jib' version "${jib_version}"
+}
+
+configurations {
+    compileOnly {
+        extendsFrom annotationProcessor
+    }
+}
+
+dependencyManagement {
+    imports {
+        mavenBom "org.testcontainers:testcontainers-bom:${testcontainers_version}"
+    }
+}
+
+dependencies {
+    implementation project(':postgresql-event-sourcing-core')
+
+    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
+    implementation 'org.springframework.boot:spring-boot-starter-web'
+    implementation 'org.springframework.kafka:spring-kafka'
+
+    implementation 'org.flywaydb:flyway-core'
+    implementation "org.mapstruct:mapstruct:${mapstruct_version}"
+
+    compileOnly 'org.projectlombok:lombok'
+    annotationProcessor 'org.projectlombok:lombok'
+
+    annotationProcessor "org.mapstruct:mapstruct-processor:${mapstruct_version}"
+    annotationProcessor "org.projectlombok:lombok-mapstruct-binding:${lombok_mapstruct_binding_version}"
+
+    testImplementation 'org.springframework.boot:spring-boot-starter-test'
+    testImplementation 'org.springframework.kafka:spring-kafka-test'
+    testImplementation 'org.testcontainers:junit-jupiter'
+    testImplementation 'org.testcontainers:postgresql'
+    testImplementation 'org.testcontainers:kafka'
+
+    testCompileOnly 'org.projectlombok:lombok'
+    testAnnotationProcessor 'org.projectlombok:lombok'
+}
+
+tasks.named('test') {
+    useJUnitPlatform()
+}
+
+jib {
+    to.image = "eugene-khyst/postgresql-event-sourcing:${project.version}"
+    from.image = "eclipse-temurin:21-jre"
+}

src/main/java/com/example/eventsourcing/PostgresEventSourcingApplication.java renamed to event-sourcing-app/src/main/java/com/example/eventsourcing/PostgresEventSourcingApplication.java

@@ -2,10 +2,17 @@
 
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.boot.autoconfigure.domain.EntityScan;
+import org.springframework.context.annotation.ComponentScan;
+import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
 import org.springframework.scheduling.annotation.EnableAsync;
 import org.springframework.scheduling.annotation.EnableScheduling;
 
 @SpringBootApplication
+@ComponentScan("eventsourcing.postgresql")
+@ComponentScan
+@EntityScan
+@EnableJpaRepositories
 @EnableScheduling
 @EnableAsync
 public class PostgresEventSourcingApplication {

src/main/java/com/example/eventsourcing/config/KafkaTopicsConfig.java renamed to event-sourcing-app/src/main/java/com/example/eventsourcing/config/KafkaTopicsConfig.java

@@ -1,13 +1,13 @@
 package com.example.eventsourcing.controller;
 
 import com.example.eventsourcing.domain.command.*;
-import com.example.eventsourcing.projection.OrderProjection;
 import com.example.eventsourcing.dto.OrderStatus;
+import com.example.eventsourcing.projection.OrderProjection;
 import com.example.eventsourcing.repository.OrderProjectionRepository;
-import com.example.eventsourcing.service.CommandProcessor;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import eventsourcing.postgresql.service.CommandProcessor;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;

src/main/java/com/example/eventsourcing/controller/OrdersController.java renamed to event-sourcing-app/src/main/java/com/example/eventsourcing/controller/OrdersController.java

@@ -1,8 +1,8 @@
 package com.example.eventsourcing.controller;
 
-import com.example.eventsourcing.error.Error;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import eventsourcing.postgresql.error.AggregateStateException;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ControllerAdvice;
@@ -15,9 +15,10 @@ public class RestResponseEntityExceptionHandler extends ResponseEntityExceptionH
 
     private final ObjectMapper objectMapper;
 
-    @ExceptionHandler(value = {Error.class})
-    protected ResponseEntity<JsonNode> handleError(Error error) {
+    @ExceptionHandler(value = {AggregateStateException.class})
+    protected ResponseEntity<JsonNode> handleException(AggregateStateException aggregateStateException) {
         return ResponseEntity.badRequest()
-                .body(objectMapper.createObjectNode().put("error", error.getMessage()));
+                .body(objectMapper.createObjectNode()
+                        .put("error", aggregateStateException.getMessage()));
     }
 }

src/main/java/com/example/eventsourcing/controller/RestResponseEntityExceptionHandler.java renamed to event-sourcing-app/src/main/java/com/example/eventsourcing/controller/RestResponseEntityExceptionHandler.java

@@ -0,0 +1,15 @@
+package com.example.eventsourcing.domain;
+
+import eventsourcing.postgresql.domain.Aggregate;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+
+@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
+@Getter
+public enum AggregateType {
+
+    ORDER(OrderAggregate.class);
+
+    private final Class<? extends Aggregate> aggregateClass;
+}