# 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**](getting-started/README.md) - [Introduction to CQRS](getting-started/01-introduction.md) - What is CQRS and why use it? - [Installation](getting-started/02-installation.md) - NuGet packages and project setup - [Your First Command](getting-started/03-first-command.md) - Build your first command handler - [Your First Query](getting-started/04-first-query.md) - Build your first query handler - [Adding Validation](getting-started/05-adding-validation.md) - FluentValidation integration - [Choosing HTTP vs gRPC](getting-started/06-choosing-http-or-grpc.md) - When to use each protocol ### 🏗️ Architecture Understand the framework's design and patterns. - [**Architecture Overview**](architecture/README.md) - [CQRS Pattern](architecture/cqrs-pattern.md) - The CQRS pattern explained - [Metadata Discovery](architecture/metadata-discovery.md) - How metadata-driven discovery works - [Modular Solution Structure](architecture/modular-solution-structure.md) - Organizing Api, CQRS, Domain, DAL layers - [Dependency Injection](architecture/dependency-injection.md) - DI patterns and handler registration - [Extensibility Points](architecture/extensibility-points.md) - Framework extension mechanisms ### ⚡ Core Features Master the fundamental CQRS features. #### Commands - [**Commands Overview**](core-features/commands/README.md) - [Basic Commands](core-features/commands/basic-commands.md) - Commands without results - [Commands with Results](core-features/commands/commands-with-results.md) - Commands that return values - [Command Registration](core-features/commands/command-registration.md) - Registration patterns - [Command Authorization](core-features/commands/command-authorization.md) - ICommandAuthorizationService - [Command Attributes](core-features/commands/command-attributes.md) - [IgnoreCommand], [CommandName], etc. #### Queries - [**Queries Overview**](core-features/queries/README.md) - [Basic Queries](core-features/queries/basic-queries.md) - Simple query handlers - [Query Registration](core-features/queries/query-registration.md) - Registration patterns - [Query Authorization](core-features/queries/query-authorization.md) - IQueryAuthorizationService - [Query Attributes](core-features/queries/query-attributes.md) - [IgnoreQuery], [QueryName], etc. #### Validation - [**Validation Overview**](core-features/validation/README.md) - [FluentValidation Setup](core-features/validation/fluentvalidation-setup.md) - Setting up validators - [HTTP Validation](core-features/validation/http-validation.md) - RFC 7807 Problem Details - [gRPC Validation](core-features/validation/grpc-validation.md) - Google Rich Error Model - [Custom Validation](core-features/validation/custom-validation.md) - Custom validation scenarios #### Dynamic Queries - [**Dynamic Queries Overview**](core-features/dynamic-queries/README.md) - [Getting Started](core-features/dynamic-queries/getting-started.md) - First dynamic query - [Filters and Sorts](core-features/dynamic-queries/filters-and-sorts.md) - Filtering, sorting, paging - [Groups and Aggregates](core-features/dynamic-queries/groups-and-aggregates.md) - Grouping and aggregation - [Queryable Providers](core-features/dynamic-queries/queryable-providers.md) - IQueryableProvider implementation - [Alter Queryable Services](core-features/dynamic-queries/alter-queryable-services.md) - Security filters, tenant isolation - [Interceptors](core-features/dynamic-queries/interceptors.md) - IDynamicQueryInterceptorProvider ### 🌐 HTTP Integration Expose your commands and queries via HTTP endpoints. - [**HTTP Integration Overview**](http-integration/README.md) - [Endpoint Mapping](http-integration/endpoint-mapping.md) - How endpoints are generated - [Naming Conventions](http-integration/naming-conventions.md) - URL naming, custom names - [HTTP Configuration](http-integration/http-configuration.md) - Route prefixes, customization - [Swagger Integration](http-integration/swagger-integration.md) - OpenAPI/Swagger setup - [HTTP Troubleshooting](http-integration/http-troubleshooting.md) - Common HTTP issues ### 🔌 gRPC Integration Build high-performance gRPC services. - [**gRPC Integration Overview**](grpc-integration/README.md) - [Getting Started with gRPC](grpc-integration/getting-started-grpc.md) - First gRPC service - [Proto File Setup](grpc-integration/proto-file-setup.md) - .proto file creation and conventions - [Source Generators](grpc-integration/source-generators.md) - How source generators work - [Service Implementation](grpc-integration/service-implementation.md) - Generated service implementations - [gRPC Reflection](grpc-integration/grpc-reflection.md) - gRPC reflection for tools - [gRPC Clients](grpc-integration/grpc-clients.md) - Consuming gRPC services - [gRPC Troubleshooting](grpc-integration/grpc-troubleshooting.md) - Common gRPC issues ### 📡 Event Streaming Production-ready event sourcing and message queuing. #### Fundamentals - [**Event Streaming Overview**](event-streaming/README.md) - [Getting Started](event-streaming/fundamentals/getting-started.md) - First event stream - [Persistent Streams](event-streaming/fundamentals/persistent-streams.md) - Event sourcing, append-only log - [Ephemeral Streams](event-streaming/fundamentals/ephemeral-streams.md) - Message queue semantics - [Events and Workflows](event-streaming/fundamentals/events-and-workflows.md) - Defining events, workflow pattern - [Subscriptions](event-streaming/fundamentals/subscriptions.md) - Subscription modes (broadcast, queue) #### Storage - [**Storage Overview**](event-streaming/storage/README.md) - [In-Memory Storage](event-streaming/storage/in-memory-storage.md) - Development/testing storage - [PostgreSQL Storage](event-streaming/storage/postgresql-storage.md) - Production PostgreSQL setup - [Database Schema](event-streaming/storage/database-schema.md) - Schema explanation - [Connection Pooling](event-streaming/storage/connection-pooling.md) - Performance tuning #### Consumer Groups - [**Consumer Groups Overview**](event-streaming/consumer-groups/README.md) - [Getting Started](event-streaming/consumer-groups/getting-started.md) - First consumer group - [Offset Management](event-streaming/consumer-groups/offset-management.md) - Offset tracking and commits - [Commit Strategies](event-streaming/consumer-groups/commit-strategies.md) - Manual, AfterEach, AfterBatch, Periodic - [Fault Tolerance](event-streaming/consumer-groups/fault-tolerance.md) - Heartbeats, stale consumer cleanup - [Load Balancing](event-streaming/consumer-groups/load-balancing.md) - Coordinating multiple consumers #### Retention Policies - [**Retention Policies Overview**](event-streaming/retention-policies/README.md) - [Time-Based Retention](event-streaming/retention-policies/time-based-retention.md) - MaxAge configuration - [Size-Based Retention](event-streaming/retention-policies/size-based-retention.md) - MaxEventCount configuration - [Cleanup Windows](event-streaming/retention-policies/cleanup-windows.md) - Scheduled cleanup windows - [Wildcard Policies](event-streaming/retention-policies/wildcard-policies.md) - Default policies with "*" #### Event Replay - [**Event Replay Overview**](event-streaming/event-replay/README.md) - [Replay from Offset](event-streaming/event-replay/replay-from-offset.md) - Offset-based replay - [Replay from Time](event-streaming/event-replay/replay-from-time.md) - Time-based replay - [Rate Limiting](event-streaming/event-replay/rate-limiting.md) - Rate limiting for replay - [Progress Tracking](event-streaming/event-replay/progress-tracking.md) - Monitoring replay progress #### Stream Configuration - [**Stream Configuration Overview**](event-streaming/stream-configuration/README.md) - [Retention Configuration](event-streaming/stream-configuration/retention-config.md) - Per-stream retention settings - [Dead Letter Queues](event-streaming/stream-configuration/dead-letter-queues.md) - DLQ configuration - [Lifecycle Configuration](event-streaming/stream-configuration/lifecycle-config.md) - Auto-create, archive, deletion - [Performance Configuration](event-streaming/stream-configuration/performance-config.md) - Batching, compression, indexing - [Access Control](event-streaming/stream-configuration/access-control.md) - Stream-level permissions #### Projections - [**Projections Overview**](event-streaming/projections/README.md) - [Creating Projections](event-streaming/projections/creating-projections.md) - IDynamicProjection implementation - [Projection Options](event-streaming/projections/projection-options.md) - Auto-start, batching, checkpoints - [Resettable Projections](event-streaming/projections/resettable-projections.md) - IResettableProjection for rebuilding - [Checkpoint Stores](event-streaming/projections/checkpoint-stores.md) - PostgreSQL vs in-memory checkpoints #### Sagas - [**Sagas Overview**](event-streaming/sagas/README.md) - [Saga Pattern](event-streaming/sagas/saga-pattern.md) - Saga pattern fundamentals - [Creating Sagas](event-streaming/sagas/creating-sagas.md) - ISaga implementation - [Compensation](event-streaming/sagas/compensation.md) - Rollback and compensation logic - [Saga Context](event-streaming/sagas/saga-context.md) - Sharing state across steps #### gRPC Streaming - [**gRPC Streaming Overview**](event-streaming/grpc-streaming/README.md) - [Persistent Subscriptions](event-streaming/grpc-streaming/persistent-subscriptions.md) - Subscribing to persistent streams - [Queue Subscriptions](event-streaming/grpc-streaming/queue-subscriptions.md) - Queue mode with ack/nack - [gRPC Clients](event-streaming/grpc-streaming/grpc-clients.md) - Building gRPC streaming clients ### 📊 Observability Monitor and operate your applications in production. #### Health Checks - [**Health Checks Overview**](observability/health-checks/README.md) - [Stream Health](observability/health-checks/stream-health.md) - Stream health monitoring - [Consumer Health](observability/health-checks/consumer-health.md) - Consumer lag and stall detection - [ASP.NET Core Integration](observability/health-checks/aspnetcore-integration.md) - ASP.NET Core health checks - [Health Thresholds](observability/health-checks/health-thresholds.md) - Configuring degraded/unhealthy thresholds #### Metrics - [**Metrics Overview**](observability/metrics/README.md) - [OpenTelemetry Setup](observability/metrics/opentelemetry-setup.md) - OpenTelemetry integration - [Prometheus & Grafana](observability/metrics/prometheus-grafana.md) - Prometheus exporter and Grafana dashboards - [Available Metrics](observability/metrics/available-metrics.md) - Counters, histograms, gauges - [Custom Metrics](observability/metrics/custom-metrics.md) - Recording custom metrics #### Logging - [**Logging Overview**](observability/logging/README.md) - [Correlation IDs](observability/logging/correlation-ids.md) - Correlation context and propagation - [Event ID Ranges](observability/logging/event-id-ranges.md) - Log event ID categories - [Serilog Integration](observability/logging/serilog-integration.md) - Serilog setup - [Application Insights](observability/logging/application-insights.md) - Application Insights integration - [Querying Logs](observability/logging/querying-logs.md) - Log query examples #### Management API - [**Management API Overview**](observability/management-api/README.md) - [Stream Operations](observability/management-api/stream-operations.md) - List streams, get details - [Subscription Operations](observability/management-api/subscription-operations.md) - Query subscriptions - [Consumer Operations](observability/management-api/consumer-operations.md) - Consumer position and lag - [Offset Reset](observability/management-api/offset-reset.md) - Resetting consumer offsets - [API Security](observability/management-api/api-security.md) - Securing management endpoints ### 📚 Tutorials Learn through comprehensive step-by-step guides. #### Modular Solution Structure - [**Modular Solution Tutorial**](tutorials/modular-solution/README.md) - [01. Solution Structure](tutorials/modular-solution/01-solution-structure.md) - Creating project structure - [02. Domain Layer](tutorials/modular-solution/02-domain-layer.md) - Domain models and events - [03. CQRS Layer](tutorials/modular-solution/03-cqrs-layer.md) - Commands, queries, handlers - [04. DAL Layer](tutorials/modular-solution/04-dal-layer.md) - Data access with EF Core - [05. API Layer](tutorials/modular-solution/05-api-layer.md) - API project with HTTP/gRPC - [06. Testing Strategy](tutorials/modular-solution/06-testing-strategy.md) - Unit and integration tests #### Event Sourcing - [**Event Sourcing Tutorial**](tutorials/event-sourcing/README.md) - [01. Fundamentals](tutorials/event-sourcing/01-fundamentals.md) - Event sourcing fundamentals - [02. Aggregate Design](tutorials/event-sourcing/02-aggregate-design.md) - Designing aggregates - [03. Events and Workflows](tutorials/event-sourcing/03-events-and-workflows.md) - Event design and workflows - [04. Projections](tutorials/event-sourcing/04-projections.md) - Building read models - [05. Snapshots](tutorials/event-sourcing/05-snapshots.md) - Snapshot optimization - [06. Replay and Rebuild](tutorials/event-sourcing/06-replay-and-rebuild.md) - Replaying and rebuilding projections #### E-Commerce Example - [**E-Commerce Example**](tutorials/ecommerce-example/README.md) - [01. Requirements](tutorials/ecommerce-example/01-requirements.md) - Domain requirements - [02. Domain Events](tutorials/ecommerce-example/02-domain-events.md) - Order domain events - [03. Commands](tutorials/ecommerce-example/03-commands.md) - PlaceOrder, CancelOrder, etc. - [04. Queries](tutorials/ecommerce-example/04-queries.md) - GetOrder, ListOrders queries - [05. Projections](tutorials/ecommerce-example/05-projections.md) - Order summary projection - [06. Sagas](tutorials/ecommerce-example/06-sagas.md) - Order fulfillment saga - [07. HTTP API](tutorials/ecommerce-example/07-http-api.md) - HTTP endpoints - [08. gRPC API](tutorials/ecommerce-example/08-grpc-api.md) - gRPC services - [09. Complete Code](tutorials/ecommerce-example/09-complete-code.md) - Full working code ### ✨ Best Practices Production-ready patterns and recommendations. - [**Best Practices Overview**](best-practices/README.md) - [Command Design](best-practices/command-design.md) - Designing effective commands - [Query Design](best-practices/query-design.md) - Query optimization and patterns - [Event Design](best-practices/event-design.md) - Event versioning and schema evolution - [Error Handling](best-practices/error-handling.md) - Error handling strategies - [Security](best-practices/security.md) - Authentication, authorization, validation - [Performance](best-practices/performance.md) - Performance tuning and optimization - [Testing](best-practices/testing.md) - Testing handlers and integrations - [Deployment](best-practices/deployment.md) - Production deployment considerations - [Multi-Tenancy](best-practices/multi-tenancy.md) - Multi-tenant patterns ### 🔄 Migration Guides Switch from other frameworks or upgrade versions. - [**Migration Guides Overview**](migration-guides/README.md) - [From MediatR](migration-guides/from-mediatr.md) - Migrating from MediatR - [From NServiceBus](migration-guides/from-nservicebus.md) - Migrating from NServiceBus - [Upgrading Versions](migration-guides/upgrading-versions.md) - Upgrading between framework versions ### 📖 API Reference Quick reference for interfaces and classes. - [**API Reference Overview**](api-reference/README.md) - [Core Interfaces](api-reference/core-interfaces.md) - ICommandHandler, IQueryHandler - [Discovery Interfaces](api-reference/discovery-interfaces.md) - ICommandDiscovery, IQueryDiscovery - [Event Interfaces](api-reference/event-interfaces.md) - IEventStreamStore, etc. - [Future Auto-Generation](api-reference/future-autogen-note.md) - Note about XML docs + DocFX generation ### 🔧 Troubleshooting Solve common issues and get answers. - [**Troubleshooting Overview**](troubleshooting/README.md) - [Common Errors](troubleshooting/common-errors.md) - Common errors and solutions - [Validation Errors](troubleshooting/validation-errors.md) - Validation troubleshooting - [gRPC Errors](troubleshooting/grpc-errors.md) - gRPC-specific issues - [Event Streaming Errors](troubleshooting/event-streaming-errors.md) - Event streaming issues - [Consumer Lag](troubleshooting/consumer-lag.md) - Diagnosing and fixing consumer lag - [FAQ](troubleshooting/faq.md) - Frequently asked questions ### 💻 Samples Code samples and examples. - [**Samples Overview**](samples/README.md) - [Quick Snippets](samples/quick-snippets.md) - Common code snippets - [Configuration Examples](samples/configuration-examples.md) - appsettings.json examples - [Full Examples](samples/full-examples.md) - Links to Svrnty.Sample project ## Quick Links - 🏠 [Main Project README](../README.md) - 📦 [NuGet Packages](https://www.nuget.org/packages?q=Svrnty.CQRS) - 🔗 [GitHub Repository](https://git.openharbor.io/svrnty/dotnet-cqrs) - 📝 [CLAUDE.md](../CLAUDE.md) - Developer guidance for Claude AI - 🎯 [Sample Project](../Svrnty.Sample) - Working examples ## Contributing Found an issue or want to improve the documentation? - Report issues at: [GitHub Issues](https://git.openharbor.io/svrnty/dotnet-cqrs/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](getting-started/README.md) or jump straight to [Your First Command](getting-started/03-first-command.md)!