> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowwarden.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> All flowwarden.* application properties

FlowWarden is **zero-config by design**. Almost everything — checkpoint behavior, retry policies, DLQ policy, deployment strategy — is configured per-stream via annotations on your `@ChangeStream` classes. A small number of properties exist for application-wide concerns: execution mode and backend-level defaults.

## Application Properties

| Property                          | Type                       | Default      | Description                                                                                                                                                                                              |
| --------------------------------- | -------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flowwarden.default-mode`         | `IMPERATIVE` \| `REACTIVE` | `IMPERATIVE` | Execution mode for all FlowWarden streams in the application.                                                                                                                                            |
| `flowwarden.dlq.mongo.collection` | `String`                   | `_fw_dlq`    | Backend-level default MongoDB collection for the Dead Letter Queue. Per-stream override via [`@MongoDlqOptions(collection = ...)`](/reference/dead-letter-queue#mongo-specific-options-mongodlqoptions). |

```yaml theme={null}
flowwarden:
  default-mode: IMPERATIVE   # or REACTIVE
  dlq:
    mongo:
      collection: _fw_dlq    # global default; per-stream override via @MongoDlqOptions
```

<Note>
  If `flowwarden.default-mode` is not set, FlowWarden defaults to `IMPERATIVE` and logs:

  ```
  INFO  FlowWardenConfigurationValidator - No 'flowwarden.default-mode' configured, defaulting to IMPERATIVE
  ```

  Spring MVC applications can omit this property entirely. Spring WebFlux applications must set it to `REACTIVE` explicitly.
</Note>

### `flowwarden.dlq.mongo`

The MongoDB-backed `DlqStore` writes failed events to a single default collection unless a stream opts out via [`@MongoDlqOptions`](/reference/dead-letter-queue#mongo-specific-options-mongodlqoptions). The TTL index on `expiresAt` is created at startup for every collection bound to a `@DeadLetterQueue`-annotated stream.

| Property                          | Type     | Default   | Description                                                                                       |
| --------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------- |
| `flowwarden.dlq.mongo.collection` | `String` | `_fw_dlq` | Default collection name used when a stream does not declare `@MongoDlqOptions(collection = ...)`. |

This namespace is Mongo-specific. Other backends (Kafka, RabbitMQ, JDBC) ship analogous property prefixes (`flowwarden.dlq.kafka.*`, etc.) once their `DlqStore` implementations land.

### ExecutionMode values

| Value        | Description                                                                                               |
| ------------ | --------------------------------------------------------------------------------------------------------- |
| `IMPERATIVE` | Blocking mode. Uses Spring's `MongoTemplate` with dedicated threads. Handler methods return `void`.       |
| `REACTIVE`   | Non-blocking mode. Uses `ReactiveMongoTemplate` and Project Reactor. Handler methods return `Mono<Void>`. |

The mode is application-wide — you cannot mix imperative and reactive handlers in the same application. See [Handler Signatures](/reference/handler-signatures#return-types--mode-exclusivity) for the validation rules.

## What is configured by annotation, not by property

Most behavior settings live on per-stream annotations, not on `application.yml`:

| Concern                            | Where to configure                                                                                                                                 |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Resume token persistence frequency | [`@Checkpoint`](/reference/checkpoint) (`saveEveryN`, `saveIntervalSeconds`)                                                                       |
| Retry behavior on failure          | [`@RetryPolicy`](/reference/retry-policy) (`maxAttempts`, `initialDelay`, `multiplier`, `maxDelay`, `jitter`, `retryOn`, `noRetryOn`)              |
| Dead Letter Queue policy           | [`@DeadLetterQueue`](/reference/dead-letter-queue) (`enabled`, `retentionDays`, `includeOriginalDocument`, `includeStackTrace`)                    |
| Mongo-specific DLQ collection      | [`@MongoDlqOptions`](/reference/dead-letter-queue#mongo-specific-options-mongodlqoptions) (`collection`) — backend companion to `@DeadLetterQueue` |
| Multi-instance coordination        | [`@ChangeStream(deploymentMode = ...)`](/reference/change-stream#deployment)                                                                       |
| Server-side filtering              | [`@Pipeline`](/reference/pipeline)                                                                                                                 |
| Application-side filtering         | [`@Filter`](/reference/filter)                                                                                                                     |
| Custom error handling              | [`@OnError`](/reference/on-error)                                                                                                                  |
| Multi-database routing             | [`@ChangeStream(mongoTemplateRef = ...)`](/reference/change-stream#behaviour)                                                                      |

This keeps stream configuration **next to the code that uses it**, instead of fragmenting it between annotations and YAML.

## MongoDB connection

FlowWarden uses Spring Data MongoDB's auto-configured `MongoTemplate` (or `ReactiveMongoTemplate`). Configure the connection with standard Spring properties:

```yaml theme={null}
spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/mydb
```

<Warning>
  MongoDB **must** be configured as a [Replica Set](https://www.mongodb.com/docs/manual/replication/) for Change Streams to work. This applies to development environments as well. Testcontainers provisions a single-node Replica Set automatically for tests.
</Warning>

## Disabling FlowWarden globally

To disable all streams without removing the `@EnableFlowWarden` annotation, set the attribute on the annotation itself:

```java theme={null}
@SpringBootApplication
@EnableFlowWarden(enabled = false)
public class MyApplication { }
```

This is useful for maintenance mode or environment-specific profiles where streams should not start. See [@EnableFlowWarden](/reference/enable-flowwarden#disabling-flowwarden).

## See Also

<CardGroup cols={2}>
  <Card title="@EnableFlowWarden" icon="power-off" href="/reference/enable-flowwarden">
    Auto-configuration entry point and global on/off switch.
  </Card>

  <Card title="@ChangeStream" icon="satellite-dish" href="/reference/change-stream">
    Per-stream attributes — the main place to configure behavior.
  </Card>

  <Card title="Handler Signatures" icon="code" href="/reference/handler-signatures">
    Mode-dependent return type rules.
  </Card>

  <Card title="Actuator" icon="chart-line" href="/reference/actuator">
    Operational endpoints and metrics.
  </Card>
</CardGroup>