dotnet-cqrs/docs/README.md

Svrnty.CQRS Documentation

Welcome to the comprehensive developer documentation for Svrnty.CQRS, a modern implementation of the Command Query Responsibility Segregation (CQRS) pattern for .NET 10.

About Svrnty.CQRS

Svrnty.CQRS is a production-ready framework that provides:

• ✅ CQRS Pattern - Clean separation of commands and queries with handlers
• ✅ HTTP & gRPC - Automatic endpoint generation for both protocols
• ✅ Dynamic Queries - OData-like filtering, sorting, grouping, and aggregation
• ✅ FluentValidation - Integrated validation with RFC 7807 (HTTP) and Google Rich Error Model (gRPC)
• ✅ Event Streaming - Production-ready event sourcing and message queuing
• ✅ Consumer Groups - Coordinated stream processing with fault tolerance
• ✅ Observability - Health checks, metrics, structured logging, and management APIs
• ✅ AOT Compatible - Ahead-of-Time compilation support (where dependencies allow)

Documentation Sections

🚀 Getting Started

New to Svrnty.CQRS or CQRS in general? Start here!

• Getting Started Overview
• Introduction to CQRS - What is CQRS and why use it?
• Installation - NuGet packages and project setup
• Your First Command - Build your first command handler
• Your First Query - Build your first query handler
• Adding Validation - FluentValidation integration
• Choosing HTTP vs gRPC - When to use each protocol

🏗️ Architecture

Understand the framework's design and patterns.

• Architecture Overview
• CQRS Pattern - The CQRS pattern explained
• Metadata Discovery - How metadata-driven discovery works
• Modular Solution Structure - Organizing Api, CQRS, Domain, DAL layers
• Dependency Injection - DI patterns and handler registration
• Extensibility Points - Framework extension mechanisms

⚡ Core Features

Master the fundamental CQRS features.

Commands

• Commands Overview
• Basic Commands - Commands without results
• Commands with Results - Commands that return values
• Command Registration - Registration patterns
• Command Authorization - ICommandAuthorizationService
• Command Attributes - [IgnoreCommand], [CommandName], etc.

Queries

• Queries Overview
• Basic Queries - Simple query handlers
• Query Registration - Registration patterns
• Query Authorization - IQueryAuthorizationService
• Query Attributes - [IgnoreQuery], [QueryName], etc.

Validation

• Validation Overview
• FluentValidation Setup - Setting up validators
• HTTP Validation - RFC 7807 Problem Details
• gRPC Validation - Google Rich Error Model
• Custom Validation - Custom validation scenarios

Dynamic Queries

• Dynamic Queries Overview
• Getting Started - First dynamic query
• Filters and Sorts - Filtering, sorting, paging
• Groups and Aggregates - Grouping and aggregation
• Queryable Providers - IQueryableProvider implementation
• Alter Queryable Services - Security filters, tenant isolation
• Interceptors - IDynamicQueryInterceptorProvider

🌐 HTTP Integration

Expose your commands and queries via HTTP endpoints.

• HTTP Integration Overview
• Endpoint Mapping - How endpoints are generated
• Naming Conventions - URL naming, custom names
• HTTP Configuration - Route prefixes, customization
• Swagger Integration - OpenAPI/Swagger setup
• HTTP Troubleshooting - Common HTTP issues

🔌 gRPC Integration

Build high-performance gRPC services.

• gRPC Integration Overview
• Getting Started with gRPC - First gRPC service
• Proto File Setup - .proto file creation and conventions
• Source Generators - How source generators work
• Service Implementation - Generated service implementations
• gRPC Reflection - gRPC reflection for tools
• gRPC Clients - Consuming gRPC services
• gRPC Troubleshooting - Common gRPC issues

📡 Event Streaming

Production-ready event sourcing and message queuing.

Fundamentals

• Event Streaming Overview
• Getting Started - First event stream
• Persistent Streams - Event sourcing, append-only log
• Ephemeral Streams - Message queue semantics
• Events and Workflows - Defining events, workflow pattern
• Subscriptions - Subscription modes (broadcast, queue)

Storage

• Storage Overview
• In-Memory Storage - Development/testing storage
• PostgreSQL Storage - Production PostgreSQL setup
• Database Schema - Schema explanation
• Connection Pooling - Performance tuning

Consumer Groups

• Consumer Groups Overview
• Getting Started - First consumer group
• Offset Management - Offset tracking and commits
• Commit Strategies - Manual, AfterEach, AfterBatch, Periodic
• Fault Tolerance - Heartbeats, stale consumer cleanup
• Load Balancing - Coordinating multiple consumers

Retention Policies

• Retention Policies Overview
• Time-Based Retention - MaxAge configuration
• Size-Based Retention - MaxEventCount configuration
• Cleanup Windows - Scheduled cleanup windows
• Wildcard Policies - Default policies with "*"

Event Replay

• Event Replay Overview
• Replay from Offset - Offset-based replay
• Replay from Time - Time-based replay
• Rate Limiting - Rate limiting for replay
• Progress Tracking - Monitoring replay progress

Stream Configuration

• Stream Configuration Overview
• Retention Configuration - Per-stream retention settings
• Dead Letter Queues - DLQ configuration
• Lifecycle Configuration - Auto-create, archive, deletion
• Performance Configuration - Batching, compression, indexing
• Access Control - Stream-level permissions

Projections

• Projections Overview
• Creating Projections - IDynamicProjection implementation
• Projection Options - Auto-start, batching, checkpoints
• Resettable Projections - IResettableProjection for rebuilding
• Checkpoint Stores - PostgreSQL vs in-memory checkpoints

Sagas

• Sagas Overview
• Saga Pattern - Saga pattern fundamentals
• Creating Sagas - ISaga implementation
• Compensation - Rollback and compensation logic
• Saga Context - Sharing state across steps

gRPC Streaming

• gRPC Streaming Overview
• Persistent Subscriptions - Subscribing to persistent streams
• Queue Subscriptions - Queue mode with ack/nack
• gRPC Clients - Building gRPC streaming clients

📊 Observability

Monitor and operate your applications in production.

Health Checks

• Health Checks Overview
• Stream Health - Stream health monitoring
• Consumer Health - Consumer lag and stall detection
• ASP.NET Core Integration - ASP.NET Core health checks
• Health Thresholds - Configuring degraded/unhealthy thresholds

Metrics

• Metrics Overview
• OpenTelemetry Setup - OpenTelemetry integration
• Prometheus & Grafana - Prometheus exporter and Grafana dashboards
• Available Metrics - Counters, histograms, gauges
• Custom Metrics - Recording custom metrics

Logging

• Logging Overview
• Correlation IDs - Correlation context and propagation
• Event ID Ranges - Log event ID categories
• Serilog Integration - Serilog setup
• Application Insights - Application Insights integration
• Querying Logs - Log query examples

Management API

• Management API Overview
• Stream Operations - List streams, get details
• Subscription Operations - Query subscriptions
• Consumer Operations - Consumer position and lag
• Offset Reset - Resetting consumer offsets
• API Security - Securing management endpoints

📚 Tutorials

Learn through comprehensive step-by-step guides.

Modular Solution Structure

• Modular Solution Tutorial
• 01. Solution Structure - Creating project structure
• 02. Domain Layer - Domain models and events
• 03. CQRS Layer - Commands, queries, handlers
• 04. DAL Layer - Data access with EF Core
• 05. API Layer - API project with HTTP/gRPC
• 06. Testing Strategy - Unit and integration tests

Event Sourcing

• Event Sourcing Tutorial
• 01. Fundamentals - Event sourcing fundamentals
• 02. Aggregate Design - Designing aggregates
• 03. Events and Workflows - Event design and workflows
• 04. Projections - Building read models
• 05. Snapshots - Snapshot optimization
• 06. Replay and Rebuild - Replaying and rebuilding projections

E-Commerce Example

• E-Commerce Example
• 01. Requirements - Domain requirements
• 02. Domain Events - Order domain events
• 03. Commands - PlaceOrder, CancelOrder, etc.
• 04. Queries - GetOrder, ListOrders queries
• 05. Projections - Order summary projection
• 06. Sagas - Order fulfillment saga
• 07. HTTP API - HTTP endpoints
• 08. gRPC API - gRPC services
• 09. Complete Code - Full working code

✨ Best Practices

Production-ready patterns and recommendations.

• Best Practices Overview
• Command Design - Designing effective commands
• Query Design - Query optimization and patterns
• Event Design - Event versioning and schema evolution
• Error Handling - Error handling strategies
• Security - Authentication, authorization, validation
• Performance - Performance tuning and optimization
• Testing - Testing handlers and integrations
• Deployment - Production deployment considerations
• Multi-Tenancy - Multi-tenant patterns

🔄 Migration Guides

Switch from other frameworks or upgrade versions.

• Migration Guides Overview
• From MediatR - Migrating from MediatR
• From NServiceBus - Migrating from NServiceBus
• Upgrading Versions - Upgrading between framework versions

📖 API Reference

Quick reference for interfaces and classes.

• API Reference Overview
• Core Interfaces - ICommandHandler, IQueryHandler
• Discovery Interfaces - ICommandDiscovery, IQueryDiscovery
• Event Interfaces - IEventStreamStore, etc.
• Future Auto-Generation - Note about XML docs + DocFX generation

🔧 Troubleshooting

Solve common issues and get answers.

• Troubleshooting Overview
• Common Errors - Common errors and solutions
• Validation Errors - Validation troubleshooting
• gRPC Errors - gRPC-specific issues
• Event Streaming Errors - Event streaming issues
• Consumer Lag - Diagnosing and fixing consumer lag
• FAQ - Frequently asked questions

💻 Samples

Code samples and examples.

• Samples Overview
• Quick Snippets - Common code snippets
• Configuration Examples - appsettings.json examples
• Full Examples - Links to Svrnty.Sample project

Quick Links

• 🏠 Main Project README
• 📦 NuGet Packages
• 🔗 GitHub Repository
• 📝 CLAUDE.md - Developer guidance for Claude AI
• 🎯 Sample Project - Working examples

Contributing

Found an issue or want to improve the documentation?

• Report issues at: GitHub Issues
• Submit pull requests with improvements
• Follow existing documentation style and formatting

License

This project is licensed under the MIT License.

---

Ready to get started? Begin with the Getting Started Guide or jump straight to Your First Command!