> ## Documentation Index
> Fetch the complete documentation index at: https://motiadev-add-real-system-tutorial-round-2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Adapters

> Pluggable backends for iii modules — swap between in-memory, file-based, Redis, and RabbitMQ without changing your application code.

Each iii module that needs persistence or distribution uses an **adapter** — a pluggable backend that implements a fixed interface. Swap adapters in `iii-config.yaml` without touching application code.

## Pattern

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
modules:
  - class: modules::queue::QueueModule
    config:
      adapter:
        class: modules::queue::RedisAdapter
        config:
          redis_url: ${REDIS_URL:redis://localhost:6379}
```

Every adapter entry has two fields:

* `class` — the full adapter path
* `config` — adapter-specific config (omit if not needed)

## Adapter Reference

### Queue

| Adapter  | Class                                 | External dependency |
| -------- | ------------------------------------- | ------------------- |
| Built-in | `modules::queue::BuiltinQueueAdapter` | None                |
| Redis    | `modules::queue::RedisAdapter`        | Redis               |
| RabbitMQ | `modules::queue::RabbitMQAdapter`     | RabbitMQ            |

#### `modules::queue::BuiltinQueueAdapter`

Default. In-process only with retries and DLQ — does not share messages across engine instances.

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
adapter:
  class: modules::queue::BuiltinQueueAdapter
```

#### `modules::queue::RedisAdapter`

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
adapter:
  class: modules::queue::RedisAdapter
  config:
    redis_url: ${REDIS_URL:redis://localhost:6379}
```

#### `modules::queue::RabbitMQAdapter`

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
adapter:
  class: modules::queue::RabbitMQAdapter
  config:
    amqp_url: ${RABBITMQ_URL:amqp://localhost:5672}
    max_attempts: 3
    prefetch_count: 10
    queue_mode: standard   # standard | fifo
```

<Info>
  For retry behavior, dead-letter queues, and full config reference, see the [Queue module](../modules/module-queue).
</Info>

***

### State

| Adapter  | Class                                    | External dependency |
| -------- | ---------------------------------------- | ------------------- |
| KV Store | `modules::state::adapters::KvStore`      | None                |
| Redis    | `modules::state::adapters::RedisAdapter` | Redis               |
| Bridge   | `modules::state::adapters::Bridge`       | Remote iii Engine   |

#### `modules::state::adapters::KvStore`

Default. Supports in-memory or file-based persistence.

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
adapter:
  class: modules::state::adapters::KvStore
  config:
    store_method: file_based   # in_memory | file_based
    file_path: ./data/state
    save_interval_ms: 5000
```

#### `modules::state::adapters::RedisAdapter`

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
adapter:
  class: modules::state::adapters::RedisAdapter
  config:
    redis_url: ${REDIS_URL:redis://localhost:6379}
```

#### `modules::state::adapters::Bridge`

Forwards state operations to a remote iii Engine.

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
adapter:
  class: modules::state::adapters::Bridge
```

***

### Stream

| Adapter  | Class                                     | External dependency |
| -------- | ----------------------------------------- | ------------------- |
| KV Store | `modules::stream::adapters::KvStore`      | None                |
| Redis    | `modules::stream::adapters::RedisAdapter` | Redis               |

#### `modules::stream::adapters::KvStore`

Default. In-process only.

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
adapter:
  class: modules::stream::adapters::KvStore
  config:
    store_method: file_based   # in_memory | file_based
    file_path: ./data/stream_store
    save_interval_ms: 5000
```

#### `modules::stream::adapters::RedisAdapter`

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
adapter:
  class: modules::stream::adapters::RedisAdapter
  config:
    redis_url: ${REDIS_URL:redis://localhost:6379}
```

***

### Cron

| Adapter    | Class                             | External dependency |
| ---------- | --------------------------------- | ------------------- |
| KV Cron    | `modules::cron::KvCronAdapter`    | None                |
| Redis Cron | `modules::cron::RedisCronAdapter` | Redis               |

#### `modules::cron::KvCronAdapter`

Default. Process-local locks — jobs may run on every instance in multi-instance deployments.

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
adapter:
  class: modules::cron::KvCronAdapter
```

#### `modules::cron::RedisCronAdapter`

Distributed locking via Redis — ensures each job runs only once across all instances.

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
adapter:
  class: modules::cron::RedisCronAdapter
  config:
    redis_url: ${REDIS_URL:redis://localhost:6379}
```

***

### PubSub

| Adapter | Class                           | External dependency |
| ------- | ------------------------------- | ------------------- |
| Local   | `modules::pubsub::LocalAdapter` | None                |
| Redis   | `modules::pubsub::RedisAdapter` | Redis               |

#### `modules::pubsub::LocalAdapter`

Default. In-process broadcast — subscribers must be in the same engine process.

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
adapter:
  class: modules::pubsub::LocalAdapter
```

#### `modules::pubsub::RedisAdapter`

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
adapter:
  class: modules::pubsub::RedisAdapter
  config:
    redis_url: ${REDIS_URL:redis://localhost:6379}
```

***

## Choosing an Adapter

|            | Single instance       | Multi-instance                  |
| ---------- | --------------------- | ------------------------------- |
| **Queue**  | BuiltinQueueAdapter   | RedisAdapter or RabbitMQAdapter |
| **State**  | KvStore (file\_based) | RedisAdapter                    |
| **Stream** | KvStore               | RedisAdapter                    |
| **Cron**   | KvCronAdapter         | RedisCronAdapter                |
| **PubSub** | LocalAdapter          | RedisAdapter                    |

<Info title="Environment variables">
  Use `${VAR:default}` syntax in `iii-config.yaml` to switch adapters per environment without changing the file:

  ```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
  redis_url: ${REDIS_URL:redis://localhost:6379}
  ```
</Info>