The layers between Spring Boot and your business rules.

jafly provides command and query buses, saga and TCC engines, event publishing, service clients, policy-based security, and observability as reactive modules you add to Spring Boot.

  1. 01 Security and identity
  2. 02 Business operations
  3. 03 External services
  4. 04 Event-driven integration
  5. 05 Domain and data
  6. 06 Business coordination
  7. 07 Service operations
  8. 08 Team-wide architecture
Java 25 · Spring Boot 4.1.1 · WebFlux · Reactor
Scroll to explore

Native stack and framework

What jafly adds to Spring Boot and WebFlux.

Requests stay on Spring Boot and WebFlux. jafly adds modules and the bridges between them, and your team picks the adapters.

Security and identity

Services ask a policy port whether a Firefly principal may act. Your configured adapter answers.

With Spring Boot and WebFlux alone, your team builds
The glue between Spring Security principals, method permissions, and policy providers.
jafly provides
Principal and policy ports, a JWT resource server, method security, and policy adapters.
How it works

The resource server maps a JWT to a Firefly principal and asks PolicyDecisionPort to allow or deny the requested URL. @Secure guards methods.

The embedded policy adapter is the default. The opt-in header bridge rewrites identity headers on authenticated requests. Don’t trust client-sent identity headers on permit-all paths: they pass through unchanged.

See the implementation

Business operations

A handled command can publish its events and clear cached queries through jafly’s bridges.

With Spring Boot and WebFlux alone, your team builds
Command and query handlers that call validation, authorization, events, and caches themselves.
jafly provides
Command and query buses, a query cache, and bridges to EDA.
How it works

CqrsEdaAutoConfiguration adds the event bridge when an EventPublisherFactory exists, and the cache bridge when a query cache does.

Annotation validation runs only when a Jakarta Validator bean exists.

See the implementation

External services

Teams call other services through the REST, SOAP, and gRPC builders on ServiceClient.

With Spring Boot and WebFlux alone, your team builds
Client wrappers with retry and failure conventions you define per protocol.
jafly provides
Protocol builders with error mapping and configurable retry and circuit-breaker policies.
How it works

ServiceClient builds REST, SOAP, and gRPC clients. REST calls retry with backoff inside a per-service circuit breaker.

REST policies don’t extend to SOAP or gRPC. REST clients retry up to three times by default. Call noRetry() on a request that isn’t safe to repeat.

See the implementation

Event-driven integration

Modules publish through the event core’s API, and the deployment picks Spring events, Kafka, RabbitMQ, or PostgreSQL.

With Spring Boot and WebFlux alone, your team builds
Envelopes, listeners, and failure handling per broker, and the code that picks a transport.
jafly provides
Event contracts with selectable transports for publishing and consuming.
How it works

EventPublisherFactory selects a publisher by type and connection. The PostgreSQL consumer listens for notifications and polls as a fallback.

The PostgreSQL publisher writes on its own connection, outside your business transaction.

See the implementation

Domain and data

Queries share filter and paging helpers. A service that needs event history adds the event-sourcing module.

With Spring Boot and WebFlux alone, your team builds
Repository, filtering, aggregate, and event-history conventions, built on Spring Data.
jafly provides
R2DBC filtering and pagination helpers. An optional module adds event sourcing with snapshots and projections.
How it works

FilterUtils turns a filter DTO into a paged PostgreSQL query. R2dbcEventStore appends after an expected-version check and writes a configured outbox in the same transaction.

Event sourcing applies only where you choose it. Other table writes need explicit transaction wiring, and version checks don’t make processing exactly once.

See the implementation

Business coordination

A saga’s steps declare their dependencies and compensations, and the saga result carries an execution report.

With Spring Boot and WebFlux alone, your team builds
Step dependencies, recovery state, and compensating actions, assembled around service calls.
jafly provides
Coordination engines with execution reports and bridges to the event and telemetry modules.
How it works

After compensation, SagaEngine sends failed steps to a dead-letter store, in memory unless you supply one, and records the final state.

Lifecycle events need an EDA publisher and are off by default. A failed state write is logged and skipped. Test restart recovery before you rely on it.

See the implementation

Service operations

Every metric in a service’s registry carries application and environment tags.

With Spring Boot and WebFlux alone, your team builds
Metric tags, health checks, and management endpoints, set up per service.
jafly provides
An observability module that tags and correlates the telemetry you configure.
How it works

A WebClient customizer forwards X-Transaction-Id. The command bus records metrics, and orchestration traces each run when an observation registry exists.

X-Transaction-Id correlates calls and starts no distributed transaction. Check trace propagation on the service client: it builds its own WebClient.

See the implementation

Team-wide architecture

Platform teams pin module versions in one BOM, and starters pull in the modules for a service layer.

With Spring Boot and WebFlux alone, your team builds
Dependency version alignment, service-layer bundles, and shared wiring.
jafly provides
A parent POM, a BOM, and starters that bring in a service layer’s modules.
How it works

The domain starter bundles CQRS, orchestration, the client, and EDA.

Starters leave each module’s activation defaults as they are. Your service’s tests should cover the set it uses.

See the implementation
Already in the native stack
Spring provides dependency injection, WebFlux request validation, reactive method authorization, and data access. A team with established Spring conventions may already have a command coordinator.
Your team still owns
Business rules, permission decisions, trusted actor and tenant context, compensating actions, and consumer idempotency. The command bus doesn’t make a command transactional or exactly once.

Request path

How a command moves through jafly.

Your handler makes the business decision. Annotations on the command handler and the query handlers decide which events go out and which ones clear the query cache.

A business command, its events, and the query cache

  1. Your service sends a command through the command bus.
  2. The bus validates the command and runs its authorize() check.
  3. A @PublishDomainEvent handler’s result goes to the CQRS and EDA bridge.
  4. EventPublisherFactory picks the first available transport in its AUTO order.
  5. The cache bridge clears the whole query cache when a query handler’s @InvalidateCacheOn lists the event’s type.

A command still succeeds if its event fails to publish. The cache bridge listens for Spring application events, and broker events reach it only if you connect them.

Capabilities

Pick the modules your service needs.

jafly / Conceptual architectureHTTP endpoints call command handlers, which can use reactive transactions.

Amber: Firefly modulesIvory lines: APIsAmber lines: events

Idempotent HTTP requests

When a controller request repeats its X-Idempotency-Key header, the web module returns the stored response instead of calling the handler again.

See the source

Commands and queries

Writes and reads go to separate buses and handlers. The query bus can answer a repeated query from a configured cache.

See the source

Sagas with compensation

Saga steps declare their dependencies and a compensation method. When a step fails, SagaEngine compensates the completed steps, in reverse order by default.

See the source

Try, confirm, cancel

TccEngine runs a try phase, then confirms or cancels. It records the outcome as confirmed, canceled, or failed.

See the source

Reactive data access

The R2DBC module bundles Spring Data R2DBC with the PostgreSQL driver. R2dbcMetrics times and counts the queries your repositories wrap.

See the source

Metrics, tracing, and health

The observability module adds application and environment tags, a tracing helper, and a health-to-metrics bridge. A firefly.observability property switches each off.

See the source

The Java modules behind each feature.

Orchestration

The saga, TCC, and workflow engines all live in this module. They share its execution context, retry policies, persistence, and recovery.

Read the module guide

Events

The event core has a single publisher and listener API, with in-process Spring events built in. Kafka, RabbitMQ, and PostgreSQL are separate adapter modules.

Read the module guide

Security core

This module evaluates @Secure rules and runs the embedded policy decision point. A missing principal or a policy error denies access.

Read the module guide

R2DBC

Flyway comes bundled for schema migrations, and the health indicator probes the database with SELECT 1.

Read the module guide

Service clients

Outbound calls can find services through Eureka, Consul, Kubernetes, or a static list. The module also has OAuth2, API-key, and certificate-pinning helpers.

Read the module guide

Observability

Micrometer’s Observation API is the base, with OpenTelemetry as the default tracing bridge. The Logback configuration writes JSON logs with trace ids.

Read the module guide

Code

Read a saga from the loan application.

RegisterApplicationSaga sends its steps’ commands through the command bus. If a later step fails, removeLoanApplication deletes the application the root step created.

Walk through Lumen Lending

  1. Open the workspace

    Lumen Lending has three tiers: an experience API, a domain service, and the core system of record.

  2. Start the saga

    LoanOriginationService builds the step inputs and runs the saga by name through SagaEngine.

    See the source
  3. Check the compensation

    RegisterApplicationSagaCompensationTest fails the offer step and checks that the new application is removed.

    See the source
RegisterApplicationSaga.java
    @SagaStep(id = STEP_REGISTER_LOAN_APPLICATION, compensate = COMPENSATE_REMOVE_LOAN_APPLICATION)
    @StepEvent(type = EVENT_LOAN_APPLICATION_REGISTERED)
    public Mono<UUID> registerLoanApplication(RegisterLoanApplicationCommand command, ExecutionContext ctx) {
        return commandBus.send(command)
                .doOnNext(loanApplicationId -> ctx.putVariable(CTX_LOAN_APPLICATION_ID, loanApplicationId));
    }

    /** Compensation for the root step: delete the application created above. */
    public Mono<Void> removeLoanApplication(UUID loanApplicationId) {
        return client.removeLoanApplication(loanApplicationId);
    }

    // ---------------------------------------------------------------------
    // Dependent step: attach the applicant party (after the root step).
    // ---------------------------------------------------------------------

    @SagaStep(id = STEP_REGISTER_APPLICANT,
            compensate = COMPENSATE_REMOVE_APPLICANT,
            dependsOn = STEP_REGISTER_LOAN_APPLICATION)
    @StepEvent(type = EVENT_APPLICANT_REGISTERED)
    public Mono<UUID> registerApplicant(RegisterApplicantCommand command, ExecutionContext ctx) {
        UUID loanApplicationId = ctx.getVariableAs(CTX_LOAN_APPLICATION_ID, UUID.class);
        return commandBus.send(command.withLoanApplicationId(loanApplicationId));
    }

Validation and authorization before the handler

A failed check ends the chain before your handler runs. jafly runs validation before authorization, and each command defines its own checks.

DefaultCommandBus.java · lines 244–262
                    return validationService.validateCommand(command)
                            .then(Mono.defer(() -> {
                                // Step 4: Authorize command with context (if authorization is enabled)
                                if (authorizationService != null) {
                                    return authorizationService.authorizeCommand(command, context);
                                } else {
                                    return Mono.empty(); // Skip authorization
                                }
                            }))
                            .then(Mono.defer(() -> {
                                // Step 5: Execute handler with context
                                try {
                                    return handler.handle(command, context);
                                } catch (Exception e) {
                                    return Mono.error(CommandProcessingException.forCommandFailure(
                                        command, handler, Duration.between(startTime, Instant.now()), e
                                    ));
                                }
                            }))

Releases and setup

Install jafly and follow the book.

Register a handler for the commands you send. Override authorize() on any command that needs a permission check, because the default allows it.

The cited modules publish v26.07.06, with tests for command authorization, saga compensation, and filtering. The parent pins Spring Boot 3.5.10.

Orchestration state is in memory unless you configure Redis, a cache, or event sourcing. Compensation is not an atomic rollback of external systems.

Front cover of jafly by example

jafly by example

From Spring Boot to a connected enterprise architecture

The book builds Lumen Lending, a personal-loan origination service, through reactive APIs, domain modeling, orchestration, and infrastructure. Its code listings come from the sample, which CI builds and tests.

Read the manuscript

October 2026 edition

Next step

Run the loan application’s saga test.