CQRS pattern implementation with reactive command/query buses, execution contexts, authorization, validation, and metrics.

• Overview
• Features
• Requirements
• Installation
• Quick Start
• Configuration
• Documentation
• Contributing
• License

Firefly Framework CQRS provides a production-ready implementation of the Command Query Responsibility Segregation pattern for reactive Spring Boot microservices. It separates read (query) and write (command) operations through dedicated buses, handlers, and execution contexts.

The library features annotation-driven handler registration (@CommandHandlerComponent, @QueryHandlerComponent), fluent command/query builders, pluggable authorization with @CustomAuthorization, automatic Bean Validation integration, and comprehensive metrics collection. It supports caching at the query handler level and includes Actuator endpoints for monitoring CQRS operations.

The execution context propagates correlation IDs, tenant information, and security context across command and query processing pipelines, enabling full traceability in distributed environments.

• Reactive CommandBus and QueryBus with type-safe handler dispatch
• @CommandHandlerComponent and @QueryHandlerComponent annotations for auto-registration
• Command<R> and Query<R> marker interfaces with response types
• Context-aware handlers via ContextAwareCommandHandler and ContextAwareQueryHandler
• ExecutionContext with correlation ID, tenant, and security context propagation
• Fluent CommandBuilder and QueryBuilder APIs
• Authorization framework with @CustomAuthorization and AuthorizationService
• Automatic Bean Validation on commands and queries
• Query-level caching with @Cacheable and @CacheEvict
• CQRS health indicator and metrics endpoint for Actuator
• Configurable properties via CqrsProperties and AuthorizationProperties
• Generic type resolution for handler-to-command/query matching

• Java 21+
• Spring Boot 3.x
• Maven 3.9+

<dependency>
    <groupId>org.fireflyframework</groupId>
    <artifactId>fireflyframework-cqrs</artifactId>
    <version>26.02.07</version>
</dependency>

import org.fireflyframework.cqrs.command.*;
import org.fireflyframework.cqrs.annotations.CommandHandlerComponent;

// Define a command
public record CreateAccountCommand(String name, String email) implements Command<AccountId> {}

// Implement the handler
@CommandHandlerComponent
public class CreateAccountHandler implements CommandHandler<CreateAccountCommand, AccountId> {

    @Override
    public Mono<AccountId> handle(CreateAccountCommand command) {
        return accountService.create(command.name(), command.email());
    }
}

// Dispatch from a controller
@RestController
public class AccountController {

    private final CommandBus commandBus;

    @PostMapping("/accounts")
    public Mono<AccountId> create(@RequestBody CreateAccountCommand command) {
        return commandBus.dispatch(command);
    }
}

firefly:
  cqrs:
    validation:
      enabled: true
    authorization:
      enabled: true
    metrics:
      enabled: true
    cache:
      enabled: true

Additional documentation is available in the docs/ directory:

• Quickstart
• Architecture
• Configuration
• Developer Guide
• Event Sourcing Integration

Contributions are welcome. Please read the CONTRIBUTING.md guide for details on our code of conduct, development process, and how to submit pull requests.

Copyright 2024-2026 Firefly Software Foundation.

Licensed under the Apache License, Version 2.0. See LICENSE for details.