Skip to main content
This page answers the most common technical questions about running FlowWarden in production and how it positions against other stream-processing options. For full coverage of any topic, follow the linked guide.

​
Compatibility & prerequisites

FlowWarden requires Java 17+, Spring Boot 3.x, and MongoDB 6.0+ running as a Replica Set. Both Spring MVC and Spring WebFlux are supported.Virtual threads (Project Loom) are supported on Spring Boot 3.2+ — see the threading guide for the caveats.See the Quickstart for the full setup.
Standalone is not supported. MongoDB Change Streams require a Replica Set — this is a MongoDB API constraint, not a FlowWarden limitation. For local development, a single-node Replica Set (--replSet rs0) is enough.Sharded clusters work with MongoDB Change Streams natively. FlowWarden’s SINGLE_LEADER mode uses a single distributed lock per stream, so it remains correct across shards.
Yes. Set flowwarden.default-mode: REACTIVE in application.yml and write handlers that return Mono<Void>. The runtime uses ReactiveMongoTemplate and Project Reactor’s concatMap to preserve per-stream ordering.See Imperative vs Reactive for the decision criteria.

​
Operations & scaling

  • ALL_INSTANCES (default) — every application instance processes every event. Use for cache invalidation, local read-models, and any handler whose effect is idempotent and local.
  • SINGLE_LEADER — only one instance (the leader) processes events; others stand by. Use for non-idempotent side effects: billing, emails, payments, order processing.
AspectALL_INSTANCESSINGLE_LEADER
DuplicatesYesNo
Failover delayNone~20–80s
Idempotency requiredYesNo
Full details and timing parameters in Deployment Modes.
Leader election relies on a MongoDB lock with a 60-second TTL, renewed every 15 seconds. Standby instances poll every 20 seconds, so the worst-case failover is ~80 seconds.When the new leader takes over, it resumes from the last persisted resume token in _fw_checkpoints. The guarantee is at-least-once: an event being processed at the moment of failover may be retried by the new leader, so your handler should remain idempotent for that window. Pair SINGLE_LEADER with @Checkpoint to make failover seamless.
FlowWarden processes events sequentially per stream (one thread per @ChangeStream in imperative mode, concatMap per stream in reactive mode). Multiple streams run in parallel on independent threads — the limit per instance is your handler throughput and your JVM resources, not a hard cap from FlowWarden.If a single stream’s sequential throughput becomes the bottleneck, the recommended pattern is to fan out to a message broker (Kafka, RabbitMQ) and parallelise on the consumer side. See Threading & Scaling for the full pattern with code samples.
FlowWarden delivers events with at-least-once semantics, so the same event can reach your handler more than once — during retries, after failover, or when replaying from the DLQ. Handlers should always be idempotent (use the event’s _id, the resume token, or a business key as a dedupe marker).The Core library is intentionally write-only for the DLQ — events accumulate in _fw_dlq with the original document, error, and stack trace. Reading and replaying DLQ entries is done from the Console. See Retry & DLQ for retry policies, exception filtering, and the DLQ document schema.

​
Alternatives & positioning

Debezium is a CDC connector that extracts MongoDB changes and publishes them as Kafka events. It decouples producers from consumers and lets you fan out to multiple downstream technologies through Kafka.FlowWarden consumes Change Streams directly inside the Spring Boot application, with no Kafka in the middle. Less moving parts, less infrastructure to operate — but tighter coupling to the Spring Boot consumer.Pick Debezium when you already have a Kafka backbone and need to feed multiple heterogeneous consumers (services in different languages, data lakes, analytics). Pick FlowWarden when you want to stay on a MongoDB + Spring Boot stack and avoid Kafka operational cost.
You can also achieve a decoupled architecture with FlowWarden by isolating it in a dedicated Spring Boot microservice that consumes Change Streams and republishes events to Kafka, HTTP webhooks, or a queue (see Threading & Scaling for the Kafka fan-out pattern). The trade-off then becomes: operate Kafka + Debezium, or operate a dedicated Spring Boot service.
The MongoDB Java driver and ReactiveChangeStreamOperation provide the low-level API for opening a Change Stream and receiving events. Everything else — discovery, lifecycle, resilience, observability — is on you.FlowWarden adds a production-ready layer on top:
  • Declarative annotations: @ChangeStream, @OnInsert/@OnUpdate/@OnDelete, @Pipeline, @Filter
  • Automatic resume token persistence via @Checkpoint
  • Built-in retry policies and Dead Letter Queue (@RetryPolicy, @DeadLetterQueue)
  • Multi-instance coordination with leader election (SINGLE_LEADER mode)
  • Startup-time validation of handler signatures and configuration
  • Console-side observability when paired with the Reporter
Pick the native driver for a one-shot, highly specific use case where you want full low-level control. Pick FlowWarden as soon as you want a production-ready integration without re-implementing these cross-cutting concerns yourself.

​
See Also

Quickstart

Get a working Change Stream handler in under 5 minutes

How it Works

Startup lifecycle, event pipeline, and dual execution model

Deployment Modes

Full details on leader election and multi-instance coordination

Retry & DLQ

Exponential backoff, exception filtering, and DLQ schema