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**](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)!