dotnet-cqrs/PROJECT.md

dotnet-cqrs

Modern CQRS implementation for .NET 10 with HTTP and gRPC endpoint generation.

Purpose

Svrnty.CQRS provides a framework for implementing the Command Query Responsibility Segregation pattern in .NET applications. It automatically generates HTTP endpoints (via Minimal API) and gRPC service implementations (via source generators) from registered command and query handlers.

What It Does

• Automatic HTTP endpoints — registers handlers, generates REST endpoints at startup
• Automatic gRPC services — source-generated service implementations from .proto files
• Dynamic queries — OData-like filtering, sorting, grouping, and aggregation
• Validation — FluentValidation with RFC 7807 (HTTP) and Google Rich Error Model (gRPC)
• Dual protocol — same handlers serve both HTTP and gRPC simultaneously

How It Works

1. Define a command/query as a C# class
2. Implement a handler (ICommandHandler<T> or IQueryHandler<T, R>)
3. Register with DI: services.AddCommand<T, Handler>()
4. Framework creates metadata and discovery services at startup
5. MapSvrntyCommands() generates HTTP endpoints; MapGrpcService<>() maps gRPC services

Key Concepts

Term	Meaning
Command	An action that changes state (always POST)
Query	A request for data (POST or GET)
Discovery	Runtime service that enumerates all registered commands/queries
Source Generator	Compile-time code generation for gRPC service implementations
Dynamic Query	OData-like filtering with IQueryable providers and interceptors

Current Status

Phase	Status	Description
0	Done	Core CQRS, Minimal API, FluentValidation
1	Done	gRPC support, source generators
2	Done	Dynamic queries, dual protocol
3	Planned	Test suite, AOT compatibility