Repository: iluwatar/java-design-patterns
Issue: Explanation for Command Query Responsibility Segregation (CQRS)
Labels: type: feature
epic: documentation

In this issue, let's add a proper explanation for the pattern.

Acceptance criteria

- The pattern's README.md has been amended with an explanation
- The explanation consists of
  - Real world example
  - In plain words
  - Wikipedia says
  - Programmatic example


Issue comments:
 I'm excited to contribute to this project, and I'd like to start by working on this issue as my first contribution. Could you please assign this issue to me? I would greatly appreciate it if you could provide some guidance on how to get started with addressing this issue. 









I've updated the pattern documentation in pull request #2590 with improvements. Please review it so that I can continue enhancing the documentation for other patterns.
This issue has been automatically marked as stale because it has not had recent activity. The issue will be unassigned if no further activity occurs. Thank you for your contributions.


Pull request review comments:

Patch that resolved the issue:
diff --git a/cqrs/README.md b/cqrs/README.md
index 6ac6061ef70e..e4af36bc3c51 100644
--- a/cqrs/README.md
+++ b/cqrs/README.md
@@ -3,25 +3,89 @@ title: CQRS
 category: Architectural
 language: en
 tag:
-  - Performance
-  - Cloud distributed
+    - Event-driven
+    - Performance
+    - Scalability
 ---
 
 ## Intent
-CQRS Command Query Responsibility Segregation - Separate the query side from the command side.
+
+CQRS aims to segregate the operations that modify the state of an application (commands) from the operations that read the state (queries). This separation allows for more flexible and optimized designs, especially in complex systems.
+
+## Explanation
+
+Real world example
+
+> Imagine a modern library where the tasks of borrowing and returning books (commands) are handled at the front desk, while the task of searching for books and reading them (queries) happens in the reading area. The front desk optimizes for transaction efficiency and record-keeping, ensuring books are properly checked in and out. Meanwhile, the reading area is optimized for comfort and accessibility, making it easy for readers to find and engage with the books. This separation improves the library's overall efficiency and user experience, much like the CQRS pattern enhances a software system's performance and maintainability.
+
+In plain words
+
+> The CQRS design pattern separates the actions of modifying data (commands) from the actions of retrieving data (queries) to enhance performance, scalability, and maintainability in software systems.
+
+**Programmatic Example**
+
+One way to implement the Command Query Responsibility Segregation (CQRS) pattern is to separate the read and write operations into different services.
+
+1. Command Service: The `CommandServiceImpl` class is used for write operations. It provides methods to create authors and books, and to add books to authors. Here's a snippet of how it's used:
+
+```java
+var commands=new CommandServiceImpl();
+        commands.authorCreated(AppConstants.E_EVANS,"Eric Evans","evans@email.com");
+        commands.bookAddedToAuthor("Domain-Driven Design",60.08,AppConstants.E_EVANS);
+```
+
+2. Query Service: The `QueryServiceImpl` class is used for read operations. It provides methods to get author and book details. Here's a snippet of how it's used:
+
+```java
+var queries=new QueryServiceImpl();
+        var evans=queries.getAuthorByUsername(AppConstants.E_EVANS);
+        var dddBook=queries.getBook("Domain-Driven Design");
+```
+
+This separation of concerns allows for flexibility in how the application handles data access and manipulation, and is a key aspect of the CQRS pattern.
 
 ## Class diagram
+
 ![alt text](./etc/cqrs.png "CQRS")
 
 ## Applicability
-Use the CQRS pattern when
 
-* You want to scale the queries and commands independently.
-* You want to use different data models for queries and commands. Useful when dealing with complex domains.
-* You want to use architectures like event sourcing or task based UI.
+* Systems requiring distinct models for read and write operations for scalability and maintainability.
+* Complex domain models where the task of updating objects differs significantly from the task of reading object data.
+* Scenarios where performance optimization for read operations is crucial, and the system can benefit from different data models or databases for reads and writes.
+
+## Known Uses
+
+* Distributed Systems and Microservices Architecture, where different services manage read and write responsibilities.
+* Event-Sourced Systems, where changes to the application state are stored as a sequence of events.
+* High-Performance Web Applications, segregating read and write databases to optimize load handling.
+
+## Consequences
+
+Benefits:
+
+* Scalability: By separating read and write models, each can be scaled independently according to their specific demands.
+* Optimization: Allows for the optimization of read models for query efficiency and write models for transactional integrity.
+* Maintainability: Reduces complexity by separating the concerns, leading to cleaner, more maintainable code.
+* Flexibility: Offers the flexibility to choose different technologies for the read and write sides according to their requirements.
+
+Trade-Offs:
+
+* Complexity: Introduces complexity due to synchronization between read and write models, especially in consistency maintenance.
+* Overhead: Might be an overkill for simple systems where the benefits do not outweigh the additional complexity.
+* Learning Curve: Requires a deeper understanding and careful design to implement effectively, increasing the initial learning curve.
+
+## Related Patterns
+
+* [Event Sourcing](https://java-design-patterns.com/patterns/event-sourcing/): Often used in conjunction with CQRS, where changes to the application state are stored as a sequence of events.
+* Domain-Driven Design (DDD): CQRS fits well within the DDD context, providing clear boundaries and separation of concerns.
+* [Repository](https://java-design-patterns.com/patterns/repository/): Can be used to abstract the data layer, providing a more seamless integration between the command and query sides.
 
 ## Credits
 
+* [Patterns, Principles, and Practices of Domain-Driven Design](https://amzn.to/3vNV4Hm)
+* [Implementing Domain-Driven Design](https://amzn.to/3TJN2HH)
+* [Microsoft .NET: Architecting Applications for the Enterprise](https://amzn.to/4aktRes)
 * [Greg Young - CQRS, Task Based UIs, Event Sourcing agh!](http://codebetter.com/gregyoung/2010/02/16/cqrs-task-based-uis-event-sourcing-agh/)
 * [Martin Fowler - CQRS](https://martinfowler.com/bliki/CQRS.html)
 * [Oliver Wolf - CQRS for Great Good](https://www.youtube.com/watch?v=Ge53swja9Dw)
diff --git a/cqrs/pom.xml b/cqrs/pom.xml
index 58ad7f29a62c..ec78265cff66 100644
--- a/cqrs/pom.xml
+++ b/cqrs/pom.xml
@@ -26,55 +26,53 @@
 
 -->
 <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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <groupId>com.iluwatar</groupId>
-    <artifactId>java-design-patterns</artifactId>
-    <version>1.26.0-SNAPSHOT</version>
-  </parent>
-  <artifactId>cqrs</artifactId>
-  <dependencies>
-    <dependency>
-      <groupId>org.junit.jupiter</groupId>
-      <artifactId>junit-jupiter-engine</artifactId>
-      <scope>test</scope>
-    </dependency>
-    <dependency>
-      <groupId>com.h2database</groupId>
-      <artifactId>h2</artifactId>
-    </dependency>
-    <dependency>
-      <groupId>org.hibernate</groupId>
-      <artifactId>hibernate-core</artifactId>
-    </dependency>
-    <dependency>
-      <groupId>org.glassfish.jaxb</groupId>
-      <artifactId>jaxb-runtime</artifactId>
-      <scope>test</scope>
-    </dependency>
-    <dependency>
-      <groupId>javax.xml.bind</groupId>
-      <artifactId>jaxb-api</artifactId>
-      <scope>test</scope>
-    </dependency>
-  </dependencies>
-  <build>
-    <plugins>
-      <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
-        <artifactId>maven-assembly-plugin</artifactId>
-        <executions>
-          <execution>
-            <configuration>
-              <archive>
-                <manifest>
-                  <mainClass>com.iluwatar.cqrs.app.App</mainClass>
-                </manifest>
-              </archive>
-            </configuration>
-          </execution>
-        </executions>
-      </plugin>
-    </plugins>
-  </build>
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>com.iluwatar</groupId>
+        <artifactId>java-design-patterns</artifactId>
+        <version>1.26.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>cqrs</artifactId>
+    <dependencies>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.h2database</groupId>
+            <artifactId>h2</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.hibernate</groupId>
+            <artifactId>hibernate-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.glassfish.jaxb</groupId>
+            <artifactId>jaxb-runtime</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>javax.xml.bind</groupId>
+            <artifactId>jaxb-api</artifactId>
+        </dependency>
+    </dependencies>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-assembly-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <configuration>
+                            <archive>
+                                <manifest>
+                                    <mainClass>com.iluwatar.cqrs.app.App</mainClass>
+                                </manifest>
+                            </archive>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
 </project>


Test patch: