Add cqrs module: CQRS in Spring Boot Without a Framework

Separate write/read DataSources, a JPA command side, and two interchangeable projection listeners (sync and @Async) demonstrating the real latency-versus- freshness trade-off CQRS forces. Includes a reflection-based proof that the query side has no dependency on the write side, and a real failure/fix transcript for the -parameters compiler flag this standalone reactor doesn't inherit from spring-boot-starter-parent.
2026-10-03 20:59:55 +00:00
parent d815a37f2e
commit b4a623b889
27 changed files with 1086 additions and 0 deletions
@@ -0,0 +1,102 @@
+# cqrs
+
+Companion project for the article **[CQRS in Spring Boot Without a Framework: Separate Read Models and Projections](https://ankurm.com/cqrs-spring-boot-without-a-framework-separate-read-models-projections/)** on **[ankurm.com](https://ankurm.com)**.
+
+There is deliberately **no `docs/` folder**: the deeper material lives in collapsible "going
+deeper" sections inside the article itself, next to the paragraph each one extends.
+
+"Without a framework" means exactly that: no Axon, no Spring Modulith event publication
+registry (that's the companion [`outbox`](../outbox) module, a different post), no event
+store. Just plain Spring -- `ApplicationEventPublisher`, `@TransactionalEventListener`,
+`@Async`, two `DataSource` beans, and `JdbcTemplate`.
+
+## Versions
+
+| | |
+|---|---|
+| Spring Boot | 4.1.1 |
+| Spring Framework | 7.0.9 |
+| JDK | 25 (Temurin 25.0.4.1+1) |
+| Maven | 3.9 |
+| H2 | 2.4.240 |
+| Hibernate ORM | 7.4.5.Final |
+
+## The shape
+
+Two databases, one Spring Boot application:
+
+| | Database | Reached through | Who writes to it |
+|---|---|---|---|
+| Write side | `jdbc:h2:mem:cqrs-write` | Spring Data JPA (`OrderRepository`) | `OrderCommandService` only |
+| Read side | `jdbc:h2:mem:cqrs-read` | a single `JdbcTemplate` bean (`readJdbcTemplate`) | the projection listener only |
+
+`OrderCommandService` changes the write side and publishes an event in the same
+transaction. A projection listener reacts to that event after the transaction commits and
+updates the read side. `OrderQueryController` reads only from the read side -- see
+[`QuerySideArchitectureTest`](src/test/java/com/ankurm/cqrsdemo/QuerySideArchitectureTest.java),
+which checks that by reflection rather than by convention.
+
+## The two profiles
+
+The same projection write (`OrderSummaryWriter`, with a configurable simulated delay to
+stand in for whatever a real read-model write costs) is called two different ways:
+
+| Profile | Listener | Command path | Read model |
+|---|---|---|---|
+| *(default)* | [`SyncOrderSummaryProjection`](src/main/java/com/ankurm/cqrsdemo/read/SyncOrderSummaryProjection.java) | pays the projection's write cost | consistent the instant the command returns |
+| `async-projection` | [`AsyncOrderSummaryProjection`](src/main/java/com/ankurm/cqrsdemo/read/AsyncOrderSummaryProjection.java) | does not pay it | consistent a short, measurable while later |
+
+```bash
+mvn -pl cqrs test -Dtest=SyncProfileLatencyTest              # default profile
+mvn -pl cqrs test -Dtest=AsyncProfileStalenessWindowTest     # -Dspring.profiles.active=async-projection, set in the test
+```
+
+## Quickstart
+
+```bash
+export JAVA_HOME=/path/to/jdk-25
+mvn -pl cqrs -am spring-boot:run                       # default (sync) profile
+mvn -pl cqrs -am spring-boot:run -Dspring-boot.run.profiles=async-projection
+
+curl -X POST localhost:8080/orders \
+  -H 'Content-Type: application/json' \
+  -d '{"customerName":"Priya","lines":[{"sku":"USB-C-HUB","quantity":1,"unitPriceCents":4999}]}'
+
+curl localhost:8080/order-summaries
+```
+
+## Captured output
+
+| File | What it shows |
+|---|---|
+| [`output/00-sync-profile-latency.txt`](output/00-sync-profile-latency.txt) | the default profile: command latency includes the projection write, and the read model is already correct the instant the command returns |
+| [`output/01-async-profile-staleness-window.txt`](output/01-async-profile-staleness-window.txt) | the `async-projection` profile: the same command returns in milliseconds, and a query that lands inside the staleness window gets a real 404 for an order that was just placed |
+| [`output/02-query-side-architecture-proof.txt`](output/02-query-side-architecture-proof.txt) | reflection over the compiled `OrderQueryController` class proving its only dependency is the read-side `JdbcTemplate` |
+| [`output/03-missing-parameters-flag-failure.txt`](output/03-missing-parameters-flag-failure.txt) | the real 500 and `IllegalArgumentException` that come back from `GET /order-summaries/{orderId}` if this module is built without `<parameters>true</parameters>` -- captured by actually removing it and running the test, not reconstructed from memory |
+
+## A note for anyone copying this shape
+
+- **`DataSourceProperties` moved** in Spring Boot 4: it's now
+  `org.springframework.boot.jdbc.autoconfigure.DataSourceProperties` in artifact
+  `spring-boot-jdbc`, not `org.springframework.boot.autoconfigure.jdbc.DataSourceProperties`.
+  Same family of split as `@DataJpaTest` and `@WebMvcTest` in the
+  [`hexagonal`](../../spring-boot-demo/hexagonal) module's notes.
+- **This module, like `order-fulfillment` and `outbox`, does not inherit
+  `spring-boot-starter-parent`**, so it does not get `-parameters` passed to `javac` for
+  free. Any `@PathVariable`/`@RequestParam` relying on its own parameter name (no explicit
+  `name = "..."`) fails at request time, not at compile time -- see
+  `output/03-missing-parameters-flag-failure.txt`. Worth flagging on the way past:
+  `order-fulfillment`'s `OrderController` has the exact same unqualified `@PathVariable`,
+  in the exact same kind of module, and has never hit this -- its own test suite exercises
+  that controller only through Spring Modulith's `PublishedEventsExtension`, never a real
+  HTTP call to `GET /orders/{id}`. The bug is latent there; this module doesn't touch that
+  one, this just flags it.
+- **The first HTTP request against a freshly started test context is not a fair baseline.**
+  `AsyncProfileStalenessWindowTest` originally measured that first request directly and
+  the ~370ms of Hikari/Hibernate first-use cost looked like it came from the projection.
+  A throwaway warm-up request before the measured one fixed it -- see the comment at the
+  top of that test and the note in `output/01-async-profile-staleness-window.txt`.
+
+No `docs/` chapter directory in this repository -- the intermediate and reference-depth
+material that would normally live there is in accordion sections inside the WordPress
+post itself.
@@ -0,0 +1,20 @@
+$ mvn -pl cqrs test -Dtest=SyncProfileLatencyTest
+(default profile -- SyncOrderSummaryProjection active; its write to order_summary runs
+ on the same thread that is about to answer the command's HTTP request)
+
+2026-10-04T02:27:21.596+05:30  INFO 17202 --- [cqrs] [           main] com.zaxxer.hikari.pool.HikariPool        : HikariPool-1 - Added connection conn0: url=jdbc:h2:mem:cqrs-write user=SA
+2026-10-04T02:27:22.729+05:30  INFO 17202 --- [cqrs] [           main] com.zaxxer.hikari.pool.HikariPool        : HikariPool-2 - Added connection conn10: url=jdbc:h2:mem:cqrs-read user=SA
+
+POST /orders (sync profile) took 670 ms, orderId=9ee5b016-7a81-40f9-8d7a-d7d1959c09be
+Immediately after POST returned, GET /order-summaries/9ee5b016-7a81-40f9-8d7a-d7d1959c09be -> status=200 OK, body=OrderSummary[orderId=9ee5b016-7a81-40f9-8d7a-d7d1959c09be, customerName=Priya, itemCount=2, totalCents=7597, status=PLACED, updatedAt=2026-10-03T20:57:24.283700Z]
+
+[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
+
+Two real HikariCP pools, one per DataSource bean -- that line alone is a cheap way to
+confirm the write and read sides really are two separate connection pools to two separate
+H2 databases, not one database with two tables. The 670ms includes the 300ms the projection's
+simulated write delay adds on top of real JPA/Hibernate first-request costs (see
+output/01-async-profile-staleness-window.txt's warm-up note for what that baseline actually
+is) -- and because that write finished before the HTTP response did, the very next GET
+against the read model, with no wait at all, already sees itemCount, totalCents and status
+correctly populated.
@@ -0,0 +1,27 @@
+$ mvn -pl cqrs test -Dtest=AsyncProfileStalenessWindowTest
+(async-projection profile -- AsyncOrderSummaryProjection active; @Async hands the same
+ write off to a separate thread instead of running it inline. A throwaway warm-up POST
+ runs first and is not measured: the first HTTP request against a freshly started test
+ context pays Hikari/Hibernate first-use costs that have nothing to do with this
+ profile's actual behaviour -- measuring that cold first request directly made POST
+ /orders look like it took ~370ms even in this profile, which would have buried the
+ exact thing the test exists to show.)
+
+2026-10-04T02:27:31.206+05:30  INFO 17346 --- [cqrs] [           main] com.zaxxer.hikari.pool.HikariPool        : HikariPool-1 - Added connection conn0: url=jdbc:h2:mem:cqrs-write user=SA
+2026-10-04T02:27:32.304+05:30  INFO 17346 --- [cqrs] [           main] com.zaxxer.hikari.pool.HikariPool        : HikariPool-2 - Added connection conn10: url=jdbc:h2:mem:cqrs-read user=SA
+
+POST /orders (async profile) took 14 ms, orderId=8451a829-7ef6-4d19-b839-2d9ce5885437
+Immediately after POST returned (inside the staleness window), GET /order-summaries/8451a829-7ef6-4d19-b839-2d9ce5885437 -> status=404 NOT_FOUND, body=null
+After waiting for the projection (outside the staleness window), GET /order-summaries/8451a829-7ef6-4d19-b839-2d9ce5885437 -> status=200 OK, body=OrderSummary[orderId=8451a829-7ef6-4d19-b839-2d9ce5885437, customerName=Dev, itemCount=1, totalCents=8999, status=PLACED, updatedAt=2026-10-03T20:57:33.971972Z]
+
+[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
+
+This is the trade-off in one transcript, warmed-up and measured honestly. The identical
+command, in the identical module, against the identical 300ms simulated write cost, took
+14ms here instead of 670ms -- because the projection's write moved to another thread and
+the HTTP response stopped waiting for it. The price is the 404 on the very next line: a
+client that queries in that window, a few dozen milliseconds wide in this run, gets a
+"not found" for an order that was just placed successfully. Only after the test waits
+(Awaitility, polling every 50ms, up to 2 seconds) does the same GET return 200 with the
+order correctly summarized. Neither profile is "more correct" than the other; they are
+the same correctness guarantee, paid for at a different point in the request.
@@ -0,0 +1,17 @@
+$ mvn -pl cqrs test -Dtest=QuerySideArchitectureTest
+(plain JUnit reflection against the compiled OrderQueryController class -- no Spring
+ context started, because this is a claim about the class file, not about runtime wiring)
+
+field readJdbcTemplate : org.springframework.jdbc.core.JdbcTemplate
+OrderQueryController constructor parameter types: [class org.springframework.jdbc.core.JdbcTemplate]
+
+[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
+The whole proof is in those two lines: OrderQueryController has exactly one declared
+field and exactly one constructor parameter, and both are JdbcTemplate -- not
+OrderRepository, not an EntityManager, not anything from the com.ankurm.cqrsdemo.command
+package. A reviewer does not have to trust the Javadoc comment on the class or remember
+to check it by hand on the next change; this test fails the build the moment anyone adds
+a write-side dependency to the query side, the same way the hexagonal-architecture post's
+`mvn dependency:tree` turns "the core has no Spring dependency" from a promise into
+something Maven enforces.
@@ -0,0 +1,21 @@
+Captured by temporarily building this module without the <parameters>true</parameters>
+maven-compiler-plugin configuration (this module does not inherit spring-boot-starter-parent,
+which is what normally adds that flag for free), then running the SyncProfileLatencyTest,
+which calls GET /order-summaries/{orderId} over real HTTP. The real, unedited response and
+server-side exception:
+
+DEBUG raw body: {"timestamp":"2026-10-03T20:54:06.783Z","status":500,"error":"Internal Server Error","path":"/order-summaries/c6fc4ad0-f98e-4e05-92a8-8717e9bffced"}
+2026-10-04T02:24:06.801+05:30 ERROR 16353 --- [cqrs] [o-auto-1-exec-3] o.a.c.c.C.[.[.[/].[dispatcherServlet]    : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: java.lang.IllegalArgumentException: Name for argument of type [java.lang.String] not specified, and parameter name information not available via reflection. Ensure that the compiler uses the '-parameters' flag.] with root cause
+
+java.lang.IllegalArgumentException: Name for argument of type [java.lang.String] not specified, and parameter name information not available via reflection. Ensure that the compiler uses the '-parameters' flag.
+
+Re-adding <parameters>true</parameters> to cqrs/pom.xml's maven-compiler-plugin configuration
+and re-running the exact same test produces the green run captured in
+00-sync-profile-latency.txt, with a 200 and a real body instead of this 500.
+
+Worth noting on the way past: order-fulfillment's OrderController (post #31) has the exact
+same unqualified @PathVariable Long id, in the exact same kind of standalone-reactor module
+with no inherited parent -- it has just never been caught, because that module's own test
+suite exercises its event-publication behaviour through Spring Modulith's
+PublishedEventsExtension rather than through a real HTTP call to GET /orders/{id}. The bug is
+latent there, not fixed; flagged separately rather than changed here.
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>com.ankurm</groupId>
+    <artifactId>spring-modulith-demo</artifactId>
+    <version>1.0.0</version>
+  </parent>
+
+  <artifactId>cqrs</artifactId>
+  <packaging>jar</packaging>
+  <name>cqrs</name>
+  <description>Command/query separation with plain Spring: a JPA write model, a second H2 database
+    holding a denormalized read model that the query side reaches only through its own JdbcTemplate,
+    and two interchangeable projection listeners (synchronous and @Async) that show the actual
+    latency-versus-freshness trade-off CQRS makes you choose, not just assert.</description>
+
+  <properties>
+    <java.version>25</java.version>
+  </properties>
+
+  <dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-dependencies</artifactId>
+        <version>${spring-boot.version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-web</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-data-jpa</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-jdbc</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.h2database</groupId>
+      <artifactId>h2</artifactId>
+      <scope>runtime</scope>
+    </dependency>
+
+    <!-- Test -->
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-test</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.awaitility</groupId>
+      <artifactId>awaitility</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-resttestclient</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-restclient</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-configuration-processor</artifactId>
+      <scope>provided</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <finalName>cqrs</finalName>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <configuration>
+          <!-- This module does not inherit spring-boot-starter-parent, which is what
+               normally passes -parameters to javac for free. Without it, every
+               @PathVariable/@RequestParam here that relies on the parameter's own
+               name (no explicit name="..." attribute) fails at request time with
+               "Name for argument of type [...] not specified", a real failure,
+               reproduced and captured in cqrs/output/03-missing-parameters-flag-failure.txt,
+               not a defensive comment. -->
+          <parameters>true</parameters>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-maven-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </build>
+</project>
@@ -0,0 +1,26 @@
+package com.ankurm.cqrsdemo;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.scheduling.annotation.EnableAsync;
+
+/**
+ * Two stores, one Spring Boot app. The write side is a normal
+ * {@code spring-boot-starter-data-jpa} setup against {@code jdbc:h2:mem:cqrs-write}.
+ * The read side is a second, independent {@link javax.sql.DataSource} against
+ * {@code jdbc:h2:mem:cqrs-read}, reached only through {@link org.springframework.jdbc.core.JdbcTemplate}
+ * — see {@link com.ankurm.cqrsdemo.read.ReadSideConfig}.
+ *
+ * <p>{@code @EnableAsync} backs the {@code async-projection} profile's
+ * {@link com.ankurm.cqrsdemo.read.AsyncOrderSummaryProjection}. Without it the
+ * {@code @Async} annotation on that listener is silently ignored and it runs
+ * synchronously anyway — a real way to lose the "fast write" half of this
+ * trade-off without any error telling you so.
+ */
+@SpringBootApplication
+@EnableAsync
+public class Application {
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+}
@@ -0,0 +1,5 @@
+package com.ankurm.cqrsdemo.command;
+
+/** Published after a {@code cancel()} command commits. */
+public record OrderCancelled(String orderId) {
+}
@@ -0,0 +1,53 @@
+package com.ankurm.cqrsdemo.command;
+
+import com.ankurm.cqrsdemo.command.internal.OrderLine;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+/**
+ * The only HTTP entry point into the write side. Note what it returns: just the new
+ * order's id, nothing shaped for display. If a caller wants to show the order back to
+ * someone, that is a query — {@link com.ankurm.cqrsdemo.query.OrderQueryController},
+ * a different controller talking to a different store.
+ */
+@RestController
+public class OrderCommandController {
+
+    private final OrderCommandService commandService;
+
+    public OrderCommandController(OrderCommandService commandService) {
+        this.commandService = commandService;
+    }
+
+    public record LineRequest(String sku, int quantity, long unitPriceCents) {
+    }
+
+    public record PlaceOrderRequest(String customerName, List<LineRequest> lines) {
+    }
+
+    public record PlaceOrderResponse(String orderId) {
+    }
+
+    @PostMapping("/orders")
+    public PlaceOrderResponse placeOrder(@RequestBody PlaceOrderRequest request) {
+        List<OrderLine> lines = request.lines().stream()
+                .map(l -> new OrderLine(l.sku(), l.quantity(), l.unitPriceCents()))
+                .toList();
+        String orderId = commandService.placeOrder(request.customerName(), lines);
+        return new PlaceOrderResponse(orderId);
+    }
+
+    @PostMapping("/orders/{orderId}/ship")
+    public void ship(@PathVariable String orderId) {
+        commandService.shipOrder(orderId);
+    }
+
+    @PostMapping("/orders/{orderId}/cancel")
+    public void cancel(@PathVariable String orderId) {
+        commandService.cancelOrder(orderId);
+    }
+}
@@ -0,0 +1,65 @@
+package com.ankurm.cqrsdemo.command;
+
+import com.ankurm.cqrsdemo.command.internal.Order;
+import com.ankurm.cqrsdemo.command.internal.OrderLine;
+import com.ankurm.cqrsdemo.command.internal.OrderRepository;
+import org.springframework.context.ApplicationEventPublisher;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+import java.util.NoSuchElementException;
+import java.util.UUID;
+
+/**
+ * Every command method does exactly two things in one transaction: change the
+ * {@code orders}/{@code order_lines} tables, and publish the event that says so.
+ * It never touches a read-model table and has no idea one exists.
+ *
+ * <p>The events are published through plain {@link ApplicationEventPublisher}, not
+ * Spring Modulith's event publication registry that the companion {@code outbox}
+ * module (post <a href="https://ankurm.com/transactional-outbox-spring-modulith-event-publication-registry/">#33</a>)
+ * builds around. That is a deliberate scope line: this module is about the shape of
+ * CQRS itself — two stores, one path in, one path out, a projection connecting them —
+ * not about guaranteeing that projection against a crash between commit and delivery.
+ * Put them together and the registry is what plugs the hole this module's events
+ * leave open; see the "going deeper" link at the end of the first section.
+ */
+@Service
+public class OrderCommandService {
+
+    private final OrderRepository orderRepository;
+    private final ApplicationEventPublisher events;
+
+    public OrderCommandService(OrderRepository orderRepository, ApplicationEventPublisher events) {
+        this.orderRepository = orderRepository;
+        this.events = events;
+    }
+
+    @Transactional
+    public String placeOrder(String customerName, List<OrderLine> lines) {
+        String orderId = UUID.randomUUID().toString();
+        Order order = new Order(orderId, customerName, lines);
+        orderRepository.save(order);
+        events.publishEvent(new OrderPlaced(orderId, customerName, lines, order.totalCents()));
+        return orderId;
+    }
+
+    @Transactional
+    public void shipOrder(String orderId) {
+        Order order = orderRepository.findById(orderId)
+                .orElseThrow(() -> new NoSuchElementException("no such order: " + orderId));
+        order.ship();
+        orderRepository.save(order);
+        events.publishEvent(new OrderShipped(orderId));
+    }
+
+    @Transactional
+    public void cancelOrder(String orderId) {
+        Order order = orderRepository.findById(orderId)
+                .orElseThrow(() -> new NoSuchElementException("no such order: " + orderId));
+        order.cancel();
+        orderRepository.save(order);
+        events.publishEvent(new OrderCancelled(orderId));
+    }
+}
@@ -0,0 +1,14 @@
+package com.ankurm.cqrsdemo.command;
+
+import com.ankurm.cqrsdemo.command.internal.OrderLine;
+
+import java.util.List;
+
+/**
+ * Published after the write-side transaction that created the order commits.
+ * This is the only thing the read side ever learns about an order being placed —
+ * it carries everything {@code OrderSummaryProjection} needs so the projection
+ * never has to call back into the write side to fill in a blank.
+ */
+public record OrderPlaced(String orderId, String customerName, List<OrderLine> lines, long totalCents) {
+}
@@ -0,0 +1,5 @@
+package com.ankurm.cqrsdemo.command;
+
+/** Published after a {@code ship()} command commits. */
+public record OrderShipped(String orderId) {
+}
@@ -0,0 +1,81 @@
+package com.ankurm.cqrsdemo.command.internal;
+
+import jakarta.persistence.CollectionTable;
+import jakarta.persistence.ElementCollection;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.Table;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * The write-side aggregate. Normalized across two tables ({@code orders} and
+ * {@code orders_lines}), because the write side's only customer is the command
+ * service — nobody queries this shape directly. {@link #status} is an enum stored
+ * as a string so a glance at the {@code orders} table tells you what it means
+ * without a lookup table.
+ */
+@Entity
+@Table(name = "orders")
+public class Order {
+
+    public enum Status { PLACED, SHIPPED, CANCELLED }
+
+    @Id
+    private String id;
+
+    private String customerName;
+
+    @Enumerated(EnumType.STRING)
+    private Status status;
+
+    @ElementCollection
+    @CollectionTable(name = "order_lines", joinColumns = @JoinColumn(name = "order_id"))
+    private List<OrderLine> lines = new ArrayList<>();
+
+    protected Order() {
+        // JPA
+    }
+
+    public Order(String id, String customerName, List<OrderLine> lines) {
+        this.id = id;
+        this.customerName = customerName;
+        this.lines = new ArrayList<>(lines);
+        this.status = Status.PLACED;
+    }
+
+    public void ship() {
+        this.status = Status.SHIPPED;
+    }
+
+    public void cancel() {
+        this.status = Status.CANCELLED;
+    }
+
+    public String id() {
+        return id;
+    }
+
+    public String customerName() {
+        return customerName;
+    }
+
+    public Status status() {
+        return status;
+    }
+
+    public List<OrderLine> lines() {
+        return Collections.unmodifiableList(lines);
+    }
+
+    public long totalCents() {
+        return lines.stream().mapToLong(OrderLine::lineTotalCents).sum();
+    }
+}
@@ -0,0 +1,43 @@
+package com.ankurm.cqrsdemo.command.internal;
+
+import jakarta.persistence.Embeddable;
+
+/**
+ * A single line of a write-side {@link Order}. {@code @Embeddable} rather than its own
+ * entity+table on purpose — the write side's job is to be correct and normalized for
+ * the one thing it does (accept commands), not to be convenient to query. That's the
+ * read side's job.
+ */
+@Embeddable
+public class OrderLine {
+
+    private String sku;
+    private int quantity;
+    private long unitPriceCents;
+
+    protected OrderLine() {
+        // JPA
+    }
+
+    public OrderLine(String sku, int quantity, long unitPriceCents) {
+        this.sku = sku;
+        this.quantity = quantity;
+        this.unitPriceCents = unitPriceCents;
+    }
+
+    public String sku() {
+        return sku;
+    }
+
+    public int quantity() {
+        return quantity;
+    }
+
+    public long unitPriceCents() {
+        return unitPriceCents;
+    }
+
+    public long lineTotalCents() {
+        return (long) quantity * unitPriceCents;
+    }
+}
@@ -0,0 +1,13 @@
+package com.ankurm.cqrsdemo.command.internal;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+/**
+ * The write side's only repository. It is package-private in spirit even though Java
+ * cannot enforce that across a single module the way Spring Modulith's {@code internal}
+ * package convention does in the sibling {@code order-fulfillment} module — see
+ * {@link com.ankurm.cqrsdemo.query.OrderQueryController} for the test that checks the
+ * query side never gets a reference to this interface.
+ */
+public interface OrderRepository extends JpaRepository<Order, String> {
+}
@@ -0,0 +1,49 @@
+package com.ankurm.cqrsdemo.config;
+
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.boot.jdbc.autoconfigure.DataSourceProperties;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+
+import javax.sql.DataSource;
+
+/**
+ * Two independent {@link DataSource} beans from two independent {@code spring.datasource.*}
+ * trees — {@code write} and {@code read} — rather than Boot's single autoconfigured
+ * {@code DataSource}. {@code writeDataSource} is {@code @Primary} so Spring Data JPA's
+ * autoconfiguration (which asks for "the" {@code DataSource} by type) wires to it without
+ * any further configuration; {@code readDataSource} is reachable only by the explicit
+ * {@code @Qualifier("readDataSource")} used in {@link com.ankurm.cqrsdemo.read.ReadSideConfig}
+ * and {@link com.ankurm.cqrsdemo.query.OrderQueryController}. There is no JPA
+ * {@code EntityManagerFactory} pointed at {@code readDataSource} at all — the read side
+ * physically has no Hibernate session to accidentally reuse.
+ */
+@Configuration
+public class DataSourceConfig {
+
+    @Bean
+    @Primary
+    @ConfigurationProperties("spring.datasource.write")
+    public DataSourceProperties writeDataSourceProperties() {
+        return new DataSourceProperties();
+    }
+
+    @Bean
+    @Primary
+    public DataSource writeDataSource(@Qualifier("writeDataSourceProperties") DataSourceProperties properties) {
+        return properties.initializeDataSourceBuilder().build();
+    }
+
+    @Bean
+    @ConfigurationProperties("spring.datasource.read")
+    public DataSourceProperties readDataSourceProperties() {
+        return new DataSourceProperties();
+    }
+
+    @Bean
+    public DataSource readDataSource(@Qualifier("readDataSourceProperties") DataSourceProperties properties) {
+        return properties.initializeDataSourceBuilder().build();
+    }
+}
@@ -0,0 +1,51 @@
+package com.ankurm.cqrsdemo.query;
+
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.http.ResponseEntity;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+/**
+ * Every method here is a {@code SELECT} against {@code order_summary} through the
+ * read-side {@link JdbcTemplate} -- nothing in this class can reach {@code OrderRepository}
+ * or an {@code EntityManager} even by accident, because it is never given one. The
+ * constructor below is the whole proof; the test for it is
+ * {@code OrderQueryControllerHasNoWriteSideAccessTest}, which inspects this exact
+ * constructor through reflection rather than trusting this comment.
+ */
+@RestController
+public class OrderQueryController {
+
+    private final JdbcTemplate readJdbcTemplate;
+
+    public OrderQueryController(@Qualifier("readJdbcTemplate") JdbcTemplate readJdbcTemplate) {
+        this.readJdbcTemplate = readJdbcTemplate;
+    }
+
+    @GetMapping("/order-summaries")
+    public List<OrderSummary> listAll() {
+        return readJdbcTemplate.query("SELECT * FROM order_summary ORDER BY updated_at DESC", this::toSummary);
+    }
+
+    @GetMapping("/order-summaries/{orderId}")
+    public ResponseEntity<OrderSummary> findOne(@PathVariable String orderId) {
+        List<OrderSummary> rows = readJdbcTemplate.query(
+                "SELECT * FROM order_summary WHERE order_id = ?",
+                this::toSummary, orderId);
+        return rows.isEmpty() ? ResponseEntity.notFound().build() : ResponseEntity.ok(rows.get(0));
+    }
+
+    private OrderSummary toSummary(java.sql.ResultSet rs, int rowNum) throws java.sql.SQLException {
+        return new OrderSummary(
+                rs.getString("order_id"),
+                rs.getString("customer_name"),
+                rs.getInt("item_count"),
+                rs.getLong("total_cents"),
+                rs.getString("status"),
+                rs.getTimestamp("updated_at").toInstant());
+    }
+}
@@ -0,0 +1,8 @@
+package com.ankurm.cqrsdemo.query;
+
+import java.time.Instant;
+
+/** The read model's own shape -- denormalized, display-ready, nothing like the write side's {@code Order}. */
+public record OrderSummary(String orderId, String customerName, int itemCount, long totalCents,
+                            String status, Instant updatedAt) {
+}
@@ -0,0 +1,48 @@
+package com.ankurm.cqrsdemo.read;
+
+import com.ankurm.cqrsdemo.command.OrderCancelled;
+import com.ankurm.cqrsdemo.command.OrderPlaced;
+import com.ankurm.cqrsdemo.command.OrderShipped;
+import org.springframework.context.annotation.Profile;
+import org.springframework.scheduling.annotation.Async;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.event.TransactionPhase;
+import org.springframework.transaction.event.TransactionalEventListener;
+
+/**
+ * The {@code async-projection} profile. {@code @Async} on a {@code @TransactionalEventListener}
+ * still waits for the write-side transaction to commit, then hands the actual call off to the
+ * {@code @EnableAsync} executor instead of running it inline -- so the HTTP response for the
+ * command returns as soon as the commit does, without waiting for the read-model write.
+ * The read model is then consistent a little while later, not immediately. See
+ * {@code output/01-async-profile-staleness-window.txt} for a query that lands inside that
+ * window and one that lands after it.
+ */
+@Component
+@Profile("async-projection")
+class AsyncOrderSummaryProjection {
+
+    private final OrderSummaryWriter writer;
+
+    AsyncOrderSummaryProjection(OrderSummaryWriter writer) {
+        this.writer = writer;
+    }
+
+    @Async
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+    void on(OrderPlaced event) {
+        writer.applyOrderPlaced(event);
+    }
+
+    @Async
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+    void on(OrderShipped event) {
+        writer.applyStatusChange(event.orderId(), "SHIPPED");
+    }
+
+    @Async
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+    void on(OrderCancelled event) {
+        writer.applyStatusChange(event.orderId(), "CANCELLED");
+    }
+}
@@ -0,0 +1,56 @@
+package com.ankurm.cqrsdemo.read;
+
+import com.ankurm.cqrsdemo.command.OrderPlaced;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Component;
+
+import java.sql.Timestamp;
+import java.time.Instant;
+
+/**
+ * The actual read-model write, shared by the synchronous and {@code @Async} projection
+ * listeners so the two profiles differ only in how they are called, never in what gets
+ * written. {@link #simulatedWriteDelayMs} stands in for whatever a real read-model write
+ * costs -- a second database round trip, a Redis call, a search index update -- so the
+ * trade-off the two profiles demonstrate is visible on a stopwatch, not just asserted.
+ */
+@Component
+class OrderSummaryWriter {
+
+    private final JdbcTemplate readJdbcTemplate;
+    private final long simulatedWriteDelayMs;
+
+    OrderSummaryWriter(JdbcTemplate readJdbcTemplate,
+                        @Value("${cqrs.projection.simulated-write-delay-ms}") long simulatedWriteDelayMs) {
+        this.readJdbcTemplate = readJdbcTemplate;
+        this.simulatedWriteDelayMs = simulatedWriteDelayMs;
+    }
+
+    void applyOrderPlaced(OrderPlaced event) {
+        sleep();
+        readJdbcTemplate.update("""
+                MERGE INTO order_summary (order_id, customer_name, item_count, total_cents, status, updated_at)
+                KEY (order_id)
+                VALUES (?, ?, ?, ?, 'PLACED', ?)
+                """,
+                event.orderId(), event.customerName(), event.lines().size(), event.totalCents(),
+                Timestamp.from(Instant.now()));
+    }
+
+    void applyStatusChange(String orderId, String status) {
+        sleep();
+        readJdbcTemplate.update(
+                "UPDATE order_summary SET status = ?, updated_at = ? WHERE order_id = ?",
+                status, Timestamp.from(Instant.now()), orderId);
+    }
+
+    private void sleep() {
+        try {
+            Thread.sleep(simulatedWriteDelayMs);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new RuntimeException(e);
+        }
+    }
+}
@@ -0,0 +1,37 @@
+package com.ankurm.cqrsdemo.read;
+
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.jdbc.core.JdbcTemplate;
+
+import javax.sql.DataSource;
+
+/**
+ * Builds the one {@link JdbcTemplate} the read side is allowed to use, against the
+ * {@code readDataSource} bean from {@link com.ankurm.cqrsdemo.config.DataSourceConfig} --
+ * never against the write side's {@code DataSource}, and creates the {@code order_summary}
+ * table it owns on startup. Boot's own {@code JdbcTemplateAutoConfiguration} would hand out
+ * a {@code JdbcTemplate} for the {@code @Primary} (write) {@code DataSource} if anyone asked
+ * for a plain, unqualified one -- which is exactly why
+ * {@link com.ankurm.cqrsdemo.query.OrderQueryController} always asks for this bean by name.
+ */
+@Configuration
+public class ReadSideConfig {
+
+    @Bean
+    public JdbcTemplate readJdbcTemplate(@Qualifier("readDataSource") DataSource readDataSource) {
+        JdbcTemplate jdbcTemplate = new JdbcTemplate(readDataSource);
+        jdbcTemplate.execute("""
+                CREATE TABLE IF NOT EXISTS order_summary (
+                  order_id       VARCHAR(64)  PRIMARY KEY,
+                  customer_name  VARCHAR(200) NOT NULL,
+                  item_count     INT          NOT NULL,
+                  total_cents    BIGINT       NOT NULL,
+                  status         VARCHAR(20)  NOT NULL,
+                  updated_at     TIMESTAMP    NOT NULL
+                )
+                """);
+        return jdbcTemplate;
+    }
+}
@@ -0,0 +1,43 @@
+package com.ankurm.cqrsdemo.read;
+
+import com.ankurm.cqrsdemo.command.OrderCancelled;
+import com.ankurm.cqrsdemo.command.OrderPlaced;
+import com.ankurm.cqrsdemo.command.OrderShipped;
+import org.springframework.context.annotation.Profile;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.event.TransactionPhase;
+import org.springframework.transaction.event.TransactionalEventListener;
+
+/**
+ * The default profile. {@code @TransactionalEventListener} with no {@code @Async} runs on
+ * the same thread that is about to return the HTTP response, after the write-side
+ * transaction has committed. The read model is guaranteed consistent by the time the
+ * command's HTTP response goes out -- at the cost of the command's latency including
+ * the read-model write. See {@code output/00-sync-profile-latency.txt} for what that
+ * actually measures to.
+ */
+@Component
+@Profile("!async-projection")
+class SyncOrderSummaryProjection {
+
+    private final OrderSummaryWriter writer;
+
+    SyncOrderSummaryProjection(OrderSummaryWriter writer) {
+        this.writer = writer;
+    }
+
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+    void on(OrderPlaced event) {
+        writer.applyOrderPlaced(event);
+    }
+
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+    void on(OrderShipped event) {
+        writer.applyStatusChange(event.orderId(), "SHIPPED");
+    }
+
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
+    void on(OrderCancelled event) {
+        writer.applyStatusChange(event.orderId(), "CANCELLED");
+    }
+}
@@ -0,0 +1,23 @@
+spring.application.name=cqrs
+
+# The write side: a normal Spring Data JPA setup. @Primary on this bean (see
+# DataSourceConfig) is what lets JPA autoconfiguration find it with no further wiring.
+spring.datasource.write.url=jdbc:h2:mem:cqrs-write;DB_CLOSE_DELAY=-1
+spring.datasource.write.driver-class-name=org.h2.Driver
+spring.datasource.write.username=sa
+spring.datasource.write.password=
+
+spring.jpa.hibernate.ddl-auto=update
+spring.jpa.open-in-view=false
+
+# The read side: a second, independent database. Reached only through the
+# readJdbcTemplate bean in ReadSideConfig -- there is no EntityManagerFactory
+# pointed at this one.
+spring.datasource.read.url=jdbc:h2:mem:cqrs-read;DB_CLOSE_DELAY=-1
+spring.datasource.read.driver-class-name=org.h2.Driver
+spring.datasource.read.username=sa
+spring.datasource.read.password=
+
+# How long the projection pretends the read-model write takes. Large enough to
+# measure reliably in a test, small enough not to make the test suite slow.
+cqrs.projection.simulated-write-delay-ms=300
@@ -0,0 +1,76 @@
+package com.ankurm.cqrsdemo;
+
+import com.ankurm.cqrsdemo.command.OrderCommandController.LineRequest;
+import com.ankurm.cqrsdemo.command.OrderCommandController.PlaceOrderRequest;
+import com.ankurm.cqrsdemo.command.OrderCommandController.PlaceOrderResponse;
+import com.ankurm.cqrsdemo.query.OrderSummary;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.resttestclient.TestRestTemplate;
+import org.springframework.boot.resttestclient.autoconfigure.AutoConfigureTestRestTemplate;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.test.context.ActiveProfiles;
+
+import java.time.Duration;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.awaitility.Awaitility.await;
+
+/**
+ * {@code async-projection} profile: {@link com.ankurm.cqrsdemo.read.AsyncOrderSummaryProjection}
+ * is active instead. {@code POST /orders} now returns as soon as the write-side transaction
+ * commits, without waiting for the simulated 300ms read-model write -- but that means a query
+ * that lands inside that window sees the order not yet in the read model at all. This test
+ * deliberately queries in both places: immediately (inside the window) and after waiting for
+ * it to close (outside the window), and both results are the real point of the test, not the
+ * final consistent one alone.
+ */
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@AutoConfigureTestRestTemplate
+@ActiveProfiles("async-projection")
+class AsyncProfileStalenessWindowTest {
+
+    @Autowired
+    private TestRestTemplate rest;
+
+    @Test
+    void placingAnOrderReturnsFastAndTheReadModelIsMomentarilyStale() {
+        // Warm-up request, deliberately not measured or asserted on: the very first HTTP
+        // request against a freshly started test context pays for connection-pool startup
+        // and Hibernate/JPA first-use costs that have nothing to do with this profile's
+        // async projection. Measuring the first request directly made the baseline ~370ms
+        // before the projection was even involved -- comfortably past the 300ms this test
+        // is trying to prove the command path *doesn't* pay. Everything after this call
+        // runs against an already-warm context.
+        rest.postForEntity("/orders", new PlaceOrderRequest("Warmup", List.of(new LineRequest("WARMUP", 1, 1))),
+                PlaceOrderResponse.class);
+
+        PlaceOrderRequest request = new PlaceOrderRequest("Dev",
+                List.of(new LineRequest("MECH-KEYBOARD", 1, 8999)));
+
+        long start = System.currentTimeMillis();
+        ResponseEntity<PlaceOrderResponse> placed = rest.postForEntity("/orders", request, PlaceOrderResponse.class);
+        long elapsedMs = System.currentTimeMillis() - start;
+
+        String orderId = placed.getBody().orderId();
+        System.out.println("POST /orders (async profile) took " + elapsedMs + " ms, orderId=" + orderId);
+        assertThat(elapsedMs).isLessThan(300L);
+
+        ResponseEntity<OrderSummary> immediately = rest.getForEntity("/order-summaries/" + orderId, OrderSummary.class);
+        System.out.println("Immediately after POST returned (inside the staleness window), "
+                + "GET /order-summaries/" + orderId + " -> status=" + immediately.getStatusCode()
+                + ", body=" + immediately.getBody());
+        assertThat(immediately.getStatusCode()).isEqualTo(HttpStatus.NOT_FOUND);
+
+        await().atMost(Duration.ofSeconds(2)).pollInterval(Duration.ofMillis(50)).untilAsserted(() -> {
+            ResponseEntity<OrderSummary> eventually = rest.getForEntity("/order-summaries/" + orderId, OrderSummary.class);
+            assertThat(eventually.getStatusCode()).isEqualTo(HttpStatus.OK);
+            System.out.println("After waiting for the projection (outside the staleness window), "
+                    + "GET /order-summaries/" + orderId + " -> status=" + eventually.getStatusCode()
+                    + ", body=" + eventually.getBody());
+        });
+    }
+}
@@ -0,0 +1,43 @@
+package com.ankurm.cqrsdemo;
+
+import com.ankurm.cqrsdemo.query.OrderQueryController;
+import org.junit.jupiter.api.Test;
+import org.springframework.jdbc.core.JdbcTemplate;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.Field;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * The query side's version of the hexagonal-architecture post's
+ * {@code mvn dependency:tree}: instead of trusting the Javadoc comment on
+ * {@link OrderQueryController} that says it cannot reach the write side, this inspects
+ * the actual compiled class through reflection. No Spring context needed -- this is a
+ * claim about the class file, not about runtime wiring.
+ */
+class QuerySideArchitectureTest {
+
+    @Test
+    void queryControllersOnlyDependencyIsTheReadJdbcTemplate() {
+        Constructor<?>[] constructors = OrderQueryController.class.getDeclaredConstructors();
+        assertThat(constructors).hasSize(1);
+
+        Class<?>[] paramTypes = constructors[0].getParameterTypes();
+        System.out.println("OrderQueryController constructor parameter types: "
+                + java.util.Arrays.toString(paramTypes));
+        assertThat(paramTypes).containsExactly(JdbcTemplate.class);
+    }
+
+    @Test
+    void queryControllerDeclaresNoFieldFromTheWriteSidePackage() {
+        Field[] fields = OrderQueryController.class.getDeclaredFields();
+        for (Field field : fields) {
+            String packageName = field.getType().getPackageName();
+            System.out.println("field " + field.getName() + " : " + field.getType().getName());
+            assertThat(packageName)
+                    .as("field %s should not be able to reference the write side", field.getName())
+                    .doesNotStartWith("com.ankurm.cqrsdemo.command");
+        }
+    }
+}
@@ -0,0 +1,51 @@
+package com.ankurm.cqrsdemo;
+
+import com.ankurm.cqrsdemo.command.OrderCommandController.LineRequest;
+import com.ankurm.cqrsdemo.command.OrderCommandController.PlaceOrderRequest;
+import com.ankurm.cqrsdemo.command.OrderCommandController.PlaceOrderResponse;
+import com.ankurm.cqrsdemo.query.OrderSummary;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.resttestclient.autoconfigure.AutoConfigureTestRestTemplate;
+import org.springframework.boot.resttestclient.TestRestTemplate;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.http.ResponseEntity;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Default profile: no {@code async-projection}, so {@link com.ankurm.cqrsdemo.read.SyncOrderSummaryProjection}
+ * is active. The projection's simulated write delay (300ms, see {@code application.properties})
+ * runs on the same thread that is about to answer the command's HTTP request, so it shows up
+ * directly in how long {@code POST /orders} takes -- and because of that, the read model is
+ * already correct the instant the command returns, with no waiting required.
+ */
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@AutoConfigureTestRestTemplate
+class SyncProfileLatencyTest {
+
+    @org.springframework.beans.factory.annotation.Autowired
+    private TestRestTemplate rest;
+
+    @Test
+    void placingAnOrderTakesAtLeastTheSimulatedProjectionDelayAndTheReadModelIsImmediatelyConsistent() {
+        PlaceOrderRequest request = new PlaceOrderRequest("Priya",
+                List.of(new LineRequest("USB-C-CABLE", 2, 1299), new LineRequest("USB-C-HUB", 1, 4999)));
+
+        long start = System.currentTimeMillis();
+        ResponseEntity<PlaceOrderResponse> placed = rest.postForEntity("/orders", request, PlaceOrderResponse.class);
+        long elapsedMs = System.currentTimeMillis() - start;
+
+        String orderId = placed.getBody().orderId();
+        System.out.println("POST /orders (sync profile) took " + elapsedMs + " ms, orderId=" + orderId);
+        assertThat(elapsedMs).isGreaterThanOrEqualTo(300L);
+
+        ResponseEntity<OrderSummary> summary = rest.getForEntity("/order-summaries/" + orderId, OrderSummary.class);
+        System.out.println("Immediately after POST returned, GET /order-summaries/" + orderId
+                + " -> status=" + summary.getStatusCode() + ", body=" + summary.getBody());
+        assertThat(summary.getBody()).isNotNull();
+        assertThat(summary.getBody().totalCents()).isEqualTo(2 * 1299 + 4999);
+        assertThat(summary.getBody().status()).isEqualTo("PLACED");
+    }
+}
@@ -15,6 +15,7 @@
    Each Maven module backs one post; modules are added over time, one commit each.
    - order-fulfillment : Spring Modulith 2.1: Enforcing Module Boundaries Inside a Spring Boot Monolith
    - outbox            : Transactional Outbox with the Spring Modulith Event Publication Registry
+    - cqrs              : CQRS in Spring Boot Without a Framework: Separate Read Models and Projections
  </description>

  <properties>
@@ -27,5 +28,6 @@
  <modules>
    <module>order-fulfillment</module>
    <module>outbox</module>
+    <module>cqrs</module>
  </modules>
 </project>