Reactive documentation #169

leopoldodonnell · 2025-04-16T13:25:06Z

Comprehensive Documentation for Reactive Domain

Overview

This PR adds complete, well-structured documentation for the Reactive Domain library. The documentation covers all aspects of the library from core concepts to advanced usage patterns, making it easier for developers to understand and use Reactive Domain effectively.

Key Changes

Complete Documentation Structure: Created a comprehensive documentation structure with a clear table of contents and navigation
Core Documentation: Added detailed documentation for:
Core concepts of event sourcing and CQRS
Usage patterns and best practices
Component documentation with logical navigation
API reference for key interfaces and classes
Architecture guide with diagrams
Migration, deployment, and security guides
Enhanced Navigation: Implemented logical progression through documentation with next/previous links
Component Navigation: Added specialized navigation for components showing their relationships
README Updates: Enhanced the main README with documentation links and status badges
Learning Path: Added a recommended learning path for new users
Documentation Sections

The documentation now includes:

Core Concepts: Fundamental principles of event sourcing and CQRS
Usage Patterns: Common patterns and best practices
Component Documentation: Detailed documentation for each component
API Reference: Reference for key interfaces and classes
Architecture Guide: High-level architecture and design principles
Migration Guide: Guidance for version upgrades
Troubleshooting Guide: Solutions for common issues
Glossary: Definitions of key terms
FAQ: Answers to common questions
Deployment Guide: Best practices for deployment
Performance Guide: Optimization techniques
Security Guide: Security best practices
Integration Guide: Integration strategies
Video Tutorial Script: Outline for video tutorials
Workshop Materials: Materials for conducting workshops

Benefits

Improved Developer Experience: Makes it easier for developers to learn and use Reactive Domain
Reduced Learning Curve: Provides clear guidance for developers new to event sourcing
Better Maintenance: Makes the codebase more maintainable with clear documentation
Increased Adoption: Makes the library more accessible to new users
Consistent Understanding: Ensures consistent understanding of concepts and patterns

Future Improvements

Set up GitHub Pages for hosting the documentation as a website
Add a GitHub Action workflow to automatically publish documentation updates
Expand code examples with more real-world scenarios
Add more diagrams to illustrate complex concepts
Screenshots

Testing

Documentation changes only
Documentation has been reviewed for accuracy, completeness, and clarity.

… links

joshkempner

ReadModelBase and the MessageBuilder factory are key components, as are the Command and Event classes that implement ICorrelatedMessage. It would be helpful to include them in the types that are covered by the docs. (Command and Event are mentioned briefly, but could be highlighted more.)

README.md

joshkempner · 2025-05-01T19:01:24Z

docs/migration.md

+
+## Breaking Changes and Deprecations
+
+### Version 2.0.0


A lot of the version numbers in this document have no connection to the actual release version numbers.

docs/api-reference/types/aggregate-root.md

joshkempner · 2025-05-01T19:18:10Z

docs/code-examples/README.md

+
+To run these examples, you'll need:
+
+- .NET Core 3.1 or later


Wrong version of .NET

docs/video-tutorial-script.md

…rences and enhance documentation - Fix GitHub badges to point to ReactiveDomain organization - Add detailed documentation for ReadModelBase component - Create comprehensive documentation for MessageBuilder factory - Enhance documentation for Command and Event classes - Add documentation for ICorrelatedMessage interface - Update repository references in workshop materials - Improve documentation structure and navigation

this shouldn't be part of the documentation, it is an artifact of for creating the documentation

…and, and Event

t fetch origin Merge branch 'reactive-documentation' of github.com:leopoldodonnell/reactive-domain into reactive-documentation Getting the branch up to date

… diagrams for key concepts

joshkempner · 2025-05-05T12:13:20Z

docs/api-reference/types/message-builder.md

+```csharp
+// Create a command with correlation information from an existing message
+ICorrelatedMessage existingCommand = // ... existing command
+ICorrelatedMessage newCommand = MessageBuilder.From(existingCommand, () => new DepositFunds(accountId, amount));


This should be

ICorrelatedMessage newCommand = MessageBuilder.From(existingCommand).Build(() => new DepositFunds(accountId, amount));

It seems the Build method is missing from the class definition above, so not surprising that it's missing here.

joshkempner · 2025-05-05T12:15:17Z

docs/api-reference/types/message-builder.md

+### In an Aggregate
+
+Messages are often created within aggregates in response to commands:
+
+```csharp
+public class Account : AggregateRoot
+{
+    public Account(Guid id, ICorrelatedMessage source) : base(id)
+    {
+        // Create a new event from the source command
+        Apply(MessageBuilder.From(source, () => new AccountCreated(id)));
+    }


This should never be done this way. AggregateRoot adds correlation information automatically to raised events, and you would never want to add new correlation info when rehydrating an aggregate.

joshkempner · 2025-05-05T12:21:56Z

docs/api-reference/types/read-model-base.md

+## Integration with Event Handlers
+
+Read models are typically updated by event handlers that subscribe to domain events:
+
+```csharp
+public class AccountEventHandler : IEventHandler<AccountCreated>, IEventHandler<FundsDeposited>
+{


This makes no sense and is not how ReadModelBase should be used.

The typical usage pattern is to implement event handlers in the read model class and have those handlers subscribed to EventStream from the base class, then start playing back the event stream using Start<T>(id).

joshkempner · 2025-05-05T12:23:53Z

docs/api-reference/types/read-model-base.md

+
+Read models in Reactive Domain represent the query side of the CQRS pattern. They are optimized for querying and provide a denormalized view of the domain data. The `ReadModelBase` class provides a common foundation for implementing read models with consistent behavior.
+
+## Class Definition


This should also include a mention of using the ReaderLock object in the read model's public query methods. It gives a way to ensure cross-thread synchronization between event handlers and public query methods since the object is automatically locked in event handlers.

joshkempner · 2025-05-05T12:27:27Z

docs/api-reference/types/command.md

+    public CreateAccount(Guid accountId, string accountNumber, string customerName, 
+                         Guid correlationId, Guid causationId)
+        : base(correlationId, causationId)
+    {


This overload of the base ctor should not be used explicitly. Use the MessageBuilder factory to set correlation and causation IDs. Most classes that inherit from Command will implicitly use the default ctor.

joshkempner · 2025-05-05T12:28:11Z

docs/api-reference/types/command.md

+var depositCommand = MessageBuilder.From(createCommand, () => new DepositFunds(
+    ((CreateAccount)createCommand).AccountId, 
+    100.00m
+));


Use .From(createCommand).Build(...) here.

joshkempner · 2025-05-05T12:29:20Z

docs/api-reference/types/command.md

+Commands are typically handled by command handlers:
+
+```csharp
+public class CreateAccountHandler : ICommandHandler<CreateAccount>


This is atypical. A class that handles commands will typically implement IHandleCommand<T> for each type that it handles.

joshkempner · 2025-05-05T12:29:53Z

docs/api-reference/types/command.md

+{
+    public Account(Guid id, ICorrelatedMessage source) : base(id)
+    {
+        Apply(MessageBuilder.From(source, () => new AccountCreated(id, source.CorrelationId, source.MsgId)));


No. See previous comment about this.

joshkempner · 2025-05-05T12:31:55Z

docs/api-reference/types/event.md

+    public AccountCreated(Guid accountId, string accountNumber, string customerName, 
+                         Guid correlationId, Guid causationId)
+        : base(correlationId, causationId)


Same comment here as for Command

joshkempner · 2025-05-05T12:33:34Z

docs/api-reference/types/event.md

+var createdEvent = MessageBuilder.From(command, () => new AccountCreated(
+    Guid.NewGuid(), 
+    "ACC-123", 
+    "John Doe"


Use From().Build().

Also, while technically correct, this would only be done when creating an event to be published on a message bus, and not when creating an event to be raised on an aggregate.

joshkempner · 2025-05-05T12:34:19Z

docs/api-reference/types/event.md

+Events are typically handled by event handlers:
+
+```csharp
+public class AccountCreatedHandler : IEventHandler<AccountCreated>


Events are typically handled in services and in read models by implementing IHandle<T>.

joshkempner · 2025-05-05T12:35:38Z

docs/api-reference/types/event.md

+
+    public Account(Guid id, ICorrelatedMessage source) : base(id)
+    {
+        Apply(MessageBuilder.From(source, () => new AccountCreated(id, "ACC-" + id.ToString().Substring(0, 8), "New Customer")));


This should be Raise(new AccountCreated(...)).

Apply methods are used for rehydration, not for creating new events.

Same thing a bit lower in this example in the public Deposit method.

…reate todo list for PR 169

…oss-references

… new events

…ing explanations and diagrams

…tation files - Enhanced glossary with more precise definitions for key terms - Clarified the relationship between RaiseEvent() and Apply() methods - Standardized terminology across all documentation files - Improved component relationship descriptions - Added detailed best practices for each component - Ensured consistent event handling descriptions

…for key interfaces and classes in Reactive Domain

…ventory management domains

…ss-referencing

…leshooting guide

…irements

…nstead of From(source, () => ...)

…yntax instead of From(source, () => ...)

…tead of From(source, () => ...)

leopoldodonnell · 2025-05-12T00:14:27Z

@joshkempner - Can you review the examples again. I've made a lot of changes.

…usage patterns

…rn CQRS best practices

…ent subscription patterns

…umentation

- Added retry patterns with examples - Added circuit breaker pattern implementations - Added bulkhead pattern for isolation - Added timeout pattern strategies - Updated documentation checklist

- Added unit testing approaches for aggregates - Added event handler testing patterns - Added saga and process manager testing - Added integration testing approaches - Added event store testing patterns - Added snapshot and versioning testing - Updated documentation checklist - Updated API reference README.md

- Added advanced test fixtures with exception handling - Added event-specific test fixture with type-safe assertions - Added scenario-based test fixture for complex test cases - Added factory pattern for test fixtures - Added integration with Reactive Domain test framework - Updated documentation checklist

- Updated implementing-projections.md with modern async patterns and DI support - Updated saving-retrieving-aggregates.md with proper repository patterns - Updated handling-commands-events.md with improved command handling - Updated creating-aggregate-root.md with best practices - Added infrastructure-setup.md with modern configuration patterns - Added performance-considerations.md with optimization techniques - Updated documentation checklist to reflect completed sections - Updated API reference README with new links

- Replace inheritance notation '<|--' with standard arrow notation '-->' for better compatibility - Fix the relationship between ICorrelatedRepository and IRepository - Ensure diagram renders correctly in Markdown viewers

joshkempner

Partial review, mostly focused on AggregateRoot.

joshkempner · 2025-05-21T15:27:51Z

README.md

-[![Build Status](https://travis-ci.org/linedata/reactive-domain.svg?branch=master)](https://travis-ci.org/linedata/reactive-domain)
+[![Build Status](https://travis-ci.org/ReactiveDomain/reactive-domain.svg?branch=master)](https://travis-ci.org/ReactiveDomain/reactive-domain)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md)
+[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://reactivedomain.github.io/reactive-domain/)


This points to a URL that doesn't exist

joshkempner · 2025-05-21T15:38:04Z

docs/api-reference/types/aggregate-root.md

+    private bool _isActive;
+    private string _accountNumber;
+
+    public Account(Guid id) : base(id)


AggregateRoot does not have a ctor that takes an ID and no correlation info. It has two ctors:

A default one that's used for rehydration (and that should be redefined in any derived classes so that the Apply methods are registered)

A ctor that takes an ICorrelatedMessage. This is the standard ctor that used when making changes to the aggregate. Passing in the correlated message provides a source whose correlation and causation info are applied automatically to events that are raised using the Raise method. Derived implementations that call this ctor should also register the same event handlers as the default ctor. A common pattern is to create a private RegisterHandlers() method that is called from both ctors.

Most of the examples in this doc include calls to base ctors that don't exist.

joshkempner · 2025-05-21T15:46:34Z

docs/api-reference/types/aggregate-root.md

+        RaiseEvent(MessageBuilder.From(source, () => new AccountCreated(
+            Id, accountNumber, customerName, DateTime.UtcNow)));


RaiseEvent does not exist in AggregateRoot. The correct method to use for raising events is called Raise(). If a correlated message has been passed into the ctor or the Source property is otherwise set, Raise will apply the correct correlation and causation IDs to any events that it's given.

This same error is repeated in the other examples below.

joshkempner · 2025-05-21T15:51:26Z

docs/api-reference/types/aggregate-root.md

+### AggregateRoot(Guid, IEnumerable\<object\>)

-Initializes a new instance of the `AggregateRoot` class with the specified ID and restores it from the provided events.
+Initializes a new instance of the `AggregateRoot` class with the specified ID and restores it from the provided events. This constructor is typically used by repositories when reconstituting an aggregate from its event history.


This doesn't exist. Rehydrating an aggregate from its event history is done using EventDrivenStateMachine.RestoreFromEvents(IEnumerable<object> events).

joshkempner · 2025-05-21T15:53:22Z

docs/api-reference/types/aggregate-root.md

+```

-**Remarks**: This method records the event and applies it to the aggregate by calling the appropriate `Apply` method.
+### RaiseEvent


This doesn't exist. The method is Raise, which is defined in EventDrivenStateMachine.

joshkempner · 2025-05-21T16:18:37Z

docs/api-reference/types/aggregate-root.md

 ### TakeEvents

-Takes the recorded history of events from this aggregate.
+Takes the recorded history of events from this aggregate. This method is typically called by a repository when saving the aggregate to extract the new events that need to be persisted.


TakeEvents is also commonly used in unit tests of aggregates to validate that the correct events are raised.

joshkempner · 2025-05-21T16:20:50Z

docs/api-reference/types/aggregate-root.md

+
+### Initialize
+
+A common pattern in Reactive Domain is to use an `Initialize` method instead of raising events directly in the constructor. This allows for more explicit validation and better control over the initialization process.


This isn't really true. Raising events directly from a ctor is not uncommon. It's also pretty common for the parameterized ctors to be private and to use public factory methods for creating aggregates with different initial sets of raised events.

joshkempner · 2025-05-21T16:21:57Z

docs/api-reference/types/aggregate-root.md

-2. Use the `RaiseEvent` method to record and apply events
-3. Define public methods that represent domain operations
+1. **Create a Class**: Create a new class that inherits from `AggregateRoot`
+2. **Define State**: Define private fields to hold the aggregate's state


An important point here is that the state of the aggregate should be as minimal as possible. The only state an aggregate should have is whatever is needed for it to make future business decisions.

joshkempner · 2025-05-21T16:22:57Z

docs/api-reference/types/aggregate-root.md

+
+3. **Validate in Command Methods**: Validate all business rules in command methods before raising events. Once an event is raised, it's considered a fact that has occurred.
+
+4. **Use MessageBuilder for Events**: Always use `MessageBuilder.From(source, () => new Event(...))` to create events with proper correlation tracking.


This should say the exact opposite.

joshkempner · 2025-05-21T16:23:50Z

docs/api-reference/types/aggregate-root.md

+
+2. **Direct State Modification**: Modifying aggregate state directly instead of through events breaks the event sourcing pattern.
+
+3. **Losing Correlation**: Not using `MessageBuilder` when creating events results in lost correlation tracking.


Nope. Use the ICorrelatedMessage in the base ctor for this.

Leopold O'Donnell and others added 5 commits April 15, 2025 08:42

Add documentation prompts for Reactive Domain library

f99697a

Add comprehensive documentation for Reactive Domain library

f9b8082

Improve documentation navigation with learning path and next/previous…

7734833

… links

Add component navigation with next/previous links

ba93c45

Add documentation and project status badges to README

3f6bcfc

leopoldodonnell requested a review from a team as a code owner April 16, 2025 13:25

joshkempner reviewed May 1, 2025

View reviewed changes

Leopold O'Donnell and others added 9 commits May 3, 2025 12:00

Removed the doc-prompt ai todo list from the project

8677ee5

Delete doc-prompt.md

aa05447

this shouldn't be part of the documentation, it is an artifact of for creating the documentation

Add index for key types including ReadModelBase, MessageBuilder, Comm…

24f0f1a

…and, and Event

t pull --no-rebase origin reactive-documentation

96bd168

t fetch origin Merge branch 'reactive-documentation' of github.com:leopoldodonnell/reactive-domain into reactive-documentation Getting the branch up to date

Enhanced documentation with detailed descriptions and examples, added…

601a903

… diagrams for key concepts

Add code example files to fix broken links in documentation

dca86f9

Add remaining code examples to complete documentation

2c03ad8

Add documentation for EventRecorder and EventDrivenStateMachine classes

aa3a79b

joshkempner reviewed May 5, 2025

View reviewed changes

Leopold O'Donnell added 2 commits May 11, 2025 16:10

Fix documentation links to point to ReactiveDomain organization and c…

f46a067

…reate todo list for PR 169

Document component relationships with new architecture section and cr…

aa654aa

…oss-references

Leopold O'Donnell added 13 commits May 11, 2025 16:27

Fix code examples to use RaiseEvent() instead of Apply() for creating…

0792564

… new events

Enhance architecture documentation with detailed CQRS and Event Sourc…

b23bbd7

…ing explanations and diagrams

Complete API reference enhancements with comprehensive documentation …

21c77c4

…for key interfaces and classes in Reactive Domain

Add comprehensive real-world examples for banking, e-commerce, and in…

33df182

…ventory management domains

Improve documentation navigation and structure with comprehensive cro…

582b9bd

…ss-referencing

Enhance learning resources with comprehensive learning path and troub…

97f8667

…leshooting guide

not needed

0e0546e

Add comprehensive documentation for Event-Driven State Machine

5c48637

Fix MessageBuilder documentation to clarify correlation tracking requ…

1ef0bbf

…irements

Update command.md to use MessageBuilder.From(source).Build() syntax i…

6035ff2

…nstead of From(source, () => ...)

Update aggregate-root.md to use MessageBuilder.From(source).Build() s…

d232936

…yntax instead of From(source, () => ...)

Update event.md to use MessageBuilder.From(source).Build() syntax ins…

33309f8

…tead of From(source, () => ...)

Leopold O'Donnell added 13 commits May 12, 2025 05:26

Update event handling documentation to match best practices

6872ea6

Update command processing documentation to match best practices

ad7750e

Update aggregate implementation documentation to reflect best practices

b658357

Update repository documentation to reflect best practices and modern …

7f8ee64

…usage patterns

Update ReadModelBase and IReadModelRepository documentation with mode…

d423074

…rn CQRS best practices

Complete CQRS Implementation documentation with query handling and ev…

cdd0b8f

…ent subscription patterns

Complete event sourcing patterns and saga implementation patterns doc…

88b7e16

…umentation

Add comprehensive error handling patterns documentation

221eaf6

- Added retry patterns with examples - Added circuit breaker pattern implementations - Added bulkhead pattern for isolation - Added timeout pattern strategies - Updated documentation checklist

remove the checklist from git

b78e19f

Fix Mermaid diagram syntax in component-relationships.md

78548cc

- Replace inheritance notation '<|--' with standard arrow notation '-->' for better compatibility - Fix the relationship between ICorrelatedRepository and IRepository - Ensure diagram renders correctly in Markdown viewers

joshkempner reviewed May 21, 2025

View reviewed changes


		Read models in Reactive Domain represent the query side of the CQRS pattern. They are optimized for querying and provide a denormalized view of the domain data. The `ReadModelBase` class provides a common foundation for implementing read models with consistent behavior.

		## Class Definition

		RaiseEvent(MessageBuilder.From(source, () => new AccountCreated(
		Id, accountNumber, customerName, DateTime.UtcNow)));


		### Initialize

		A common pattern in Reactive Domain is to use an `Initialize` method instead of raising events directly in the constructor. This allows for more explicit validation and better control over the initialization process.


		3. Validate in Command Methods: Validate all business rules in command methods before raising events. Once an event is raised, it's considered a fact that has occurred.

		4. Use MessageBuilder for Events: Always use `MessageBuilder.From(source, () => new Event(...))` to create events with proper correlation tracking.


		2. Direct State Modification: Modifying aggregate state directly instead of through events breaks the event sourcing pattern.

		3. Losing Correlation: Not using `MessageBuilder` when creating events results in lost correlation tracking.

Reactive documentation #169

Are you sure you want to change the base?

Reactive documentation #169

Uh oh!

Conversation

leopoldodonnell commented Apr 16, 2025

Comprehensive Documentation for Reactive Domain

Overview

Key Changes

The documentation now includes:

Benefits

Future Improvements

Testing

Uh oh!

joshkempner left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joshkempner May 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leopoldodonnell commented May 12, 2025

Uh oh!

joshkempner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

joshkempner left a comment •

edited

Loading

joshkempner May 5, 2025 •

edited

Loading