Add workflow documentation on diff arch patterns

docs/core-concepts/cqrs.md

@@ -1,3 +1,36 @@
 # CQRS
 
-DOCUMENTATION IN PROGRESS
+CQRS separates the responsibilities of reading and writing data, allowing for
+optimized and scalable operations by using different models for command (write)
+and query (read) actions.
+
+## Elements
+
+| Element | Layer | Purpose  |
+| ------- | ----- | -------  |
+| Application Service | Application | Orchestrates business operations by coordinating between the domain logic and infrastructure components. |
+| Commands | Application | Imperative messages that request a specific action or change in the system, typically altering the state of the application or domain. |
+| Command Handlers | Application | Components responsible for executing the business logic associated with a specific command, processing the command to perform the required action or state change. |
+| Aggregates | Domain | A cluster of domain entities that are treated as a single unit, ensuring consistency and encapsulating business logic. |
+| Events | Domain | A record of a significant change in state or behavior within the domain, which can trigger subsequent processing. |
+| Event Handlers | Domain | A component that listens for specific events and executes business logic in response to those events. |
+| Repository | Application | A data access layer that provides an abstraction for retrieving and persisting domain objects, ensuring that domain logic remains isolated from data storage concerns. |
+| Persistence Store | Infrastructure | A general-purpose storage system that holds the application's data, typically used for saving the current state of domain objects outside of event-driven contexts. |
+| Event Store | Infrastructure | A specialized storage system that captures and persists all domain events, allowing the reconstruction of aggregate states and enabling event sourcing patterns. |
+
+
+## Workflow
+
+![CQRS](../images/cqrs-workflow.jpg)
+
+1. **Request**: A client request is made to the system, which is received by the API layer.
+2. **Command**: The API converts the request data into a Command, which is passed to the Command Handler for processing.
+3. **Command Handler**: The Command Handler receives the Command and is responsible for executing the associated business logic. It interacts with the Repository to obtain the necessary Aggregate.
+4. **Repository**: The Repository retrieves the Aggregate by hydrating it from the Persistence Store (Write Store) based on the current state.
+5. **Aggregate**: The Command Handler invokes the relevant behavior on the Aggregate, passing the data from the Command to perform a business operation.
+6. **Output**: The Aggregate processes the data and, if successful, generates an event as a result of a state change or a business operation.
+7. **Repository**: The Command Handler persists the updated Aggregate and any resulting events back through the Repository.
+8. **Persistence**: The Repository saves the updated data back into the Write Store.
+9. **Event Store**: Any events generated by the Aggregate are also stored in the Event Store for subsequent processing.
+10. **Event Handler**: The stored events are processed by the Event Handler, which reacts to specific events by triggering further actions or updating read models.
+11. **Read Models**: The Event Handler updates the Read Store with new or modified Read Models that are optimized for query operations.

docs/core-concepts/ddd.md

@@ -1,3 +1,29 @@
-# Pure DDD
+# DDD
 
-DOCUMENTATION IN PROGRESS
+In this pattern, you use only the tactical elements that are part of core DDD.
+
+## Elements
+
+| Element | Layer | Purpose  |
+| ------- | ----- | -------  |
+| Application Service | Application | Orchestrates business operations by coordinating between the domain logic and infrastructure components. |
+| Aggregates | Domain | A cluster of domain entities that are treated as a single unit, ensuring consistency and encapsulating business logic. |
+| Events | Domain | A record of a significant change in state or behavior within the domain, which can trigger subsequent processing. |
+| Event Handlers | Domain | A component that listens for specific events and executes business logic in response to those events. |
+| Repository | Application | A data access layer that provides an abstraction for retrieving and persisting domain objects, ensuring that domain logic remains isolated from data storage concerns. |
+| Persistence Store | Infrastructure | A general-purpose storage system that holds the application's data, typically used for saving the current state of domain objects outside of event-driven contexts. |
+| Event Store | Infrastructure | A specialized storage system that captures and persists all domain events, allowing the reconstruction of aggregate states and enabling event sourcing patterns. |
+
+## Workflow
+
+![Pure DDD](../images/ddd-workflow.jpg)
+
+1. **Request**: Application receives a client request at the API layer
+2. **DTO (Data Transfer Object)**: The API converts the request data into a DTO, encapsulating the necessary information to pass to the Application Service, and invokes a specific *use case*.
+3. **Application Service**: Application Service asks for the aggregate instance from the Repository.
+4. **Repository**: The repository hydrates an aggregate from the Persistence Store.
+5. **Aggregate**: The Application Service invokes the correct behavior on the Aggregate along with request data.
+6. **Output**: The Aggregate processes the data, and if successful, an event is generated as a result of a state change or a business operation.
+7. **Repository**: The Application Service persists the processed data and events via the Repository again.
+8. **Persistence**: The Repository saves the updated data back into the Persistence Store.
+9. **Event Store**: Any events generated by the Aggregate are stored in the Event Store by the repository.

docs/core-concepts/event-sourcing.md

@@ -1,3 +1,38 @@
 # Event Sourcing
 
-DOCUMENTATION IN PROGRESS
+Event Sourcing is a pattern where the state of a system is derived by replaying
+a sequence of events, allowing complete reconstruction and auditing of past
+states.
+
+# Elements
+
+| Element | Layer | Purpose  |
+| ------- | ----- | -------  |
+| Application Service | Application | Orchestrates business operations by coordinating between the domain logic and infrastructure components. |
+| Commands | Application | Imperative messages that request a specific action or change in the system, typically altering the state of the application or domain. |
+| Command Handlers | Application | Components responsible for executing the business logic associated with a specific command, processing the command to perform the required action or state change. |
+| Aggregates | Domain | A cluster of domain entities that are treated as a single unit, ensuring consistency and encapsulating business logic. |
+| Events | Domain | A record of a significant change in state or behavior within the domain, which can trigger subsequent processing. |
+| Event Handlers | Domain | A component that listens for specific events and executes business logic in response to those events. |
+| Repository | Application | A data access layer that provides an abstraction for retrieving and persisting domain objects, ensuring that domain logic remains isolated from data storage concerns. |
+| Event Store | Infrastructure | A specialized storage system that captures and persists all domain events, allowing the reconstruction of aggregate states and enabling event sourcing patterns. |
+
+
+## Workflow
+
+![Event Sourcing](../images/es-workflow.jpg)
+
+This workflow emphasizes the Event Sourcing pattern, where each state change
+is captured as an event, enabling complete traceability and the ability to
+reconstruct the state of the system at any point in time.
+
+1. **Request**: A client request is made to the system, which is received by the API layer.
+2. **Command**: The API layer converts the request into a Command, which encapsulates the action that should be performed, and passes it to the Command Handler.
+3. **Command Handler**: The Command Handler processes the Command, interacting with the Repository to retrieve the relevant Aggregate.
+4. **Hydrate**: The Repository hydrates the Aggregate by reconstructing its state from past events stored in the Event Store.
+5. **Aggregate**: The Command Handler invokes the appropriate method on the Aggregate to perform the required business operation.
+6. **Output**: The Aggregate processes the command, which results in a state change. Instead of directly updating the state in a persistence store, the Aggregate generates an Event that describes the change.
+7. **Repository**: The generated Event is passed back to the Repository, which is responsible for persisting the Event.
+8. **Event Store**: The Repository saves the Event in the Event Store, ensuring that all changes in the domain are captured as a series of events.
+9. **Event Handler**: The Event is then processed by an Event Handler, which reacts to the event by performing additional business logic or updating projections.
+10. **Read Models**: The Event Handler updates the Read Store with new or modified Read Models that are optimized for query operations, ensuring that the latest state can be efficiently retrieved for future read requests.

mkdocs.yml

@@ -56,6 +56,7 @@ plugins:
 markdown_extensions:
   - admonition
   - attr_list
+  - tables
   - md_in_html
   - mdx_include
   - pymdownx.details