> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/iii-hq/iii/llms.txt
> Use this file to discover all available pages before exploring further.

# Module

> Core trait for all iii framework modules

The `Module` trait is the foundation for all modules in the iii framework. Every module must implement this trait to integrate with the engine's lifecycle management, function registration, and background task execution.

## Location

```rust theme={null}
use iii::modules::module::Module;
```

Defined in `src/modules/module.rs`

## Trait Definition

```rust theme={null}
#[async_trait::async_trait]
pub trait Module: Send + Sync {
    fn name(&self) -> &'static str;
    
    async fn create(
        engine: Arc<Engine>,
        config: Option<Value>
    ) -> anyhow::Result<Box<dyn Module>>
    where
        Self: Sized;
    
    fn make_module(
        engine: Arc<Engine>,
        config: Option<Value>
    ) -> ModuleFuture
    where
        Self: Sized + 'static;
    
    async fn initialize(&self) -> anyhow::Result<()>;
    
    async fn start_background_tasks(
        &self,
        _shutdown: tokio::sync::watch::Receiver<bool>,
    ) -> anyhow::Result<()>;
    
    async fn destroy(&self) -> anyhow::Result<()>;
    
    fn register_functions(&self, engine: Arc<Engine>);
}
```

## Required Methods

### name

```rust theme={null}
fn name(&self) -> &'static str
```

Returns the static name of the module.

<ParamField path="return" type="&'static str">
  The module's name identifier
</ParamField>

### create

```rust theme={null}
async fn create(
    engine: Arc<Engine>,
    config: Option<Value>
) -> anyhow::Result<Box<dyn Module>>
```

Creates a new instance of the module. This is the primary constructor method.

<ParamField path="engine" type="Arc<Engine>" required>
  Reference to the iii engine instance
</ParamField>

<ParamField path="config" type="Option<Value>">
  Optional JSON configuration for the module
</ParamField>

<ParamField path="return" type="anyhow::Result<Box<dyn Module>>">
  Returns a boxed module instance or an error
</ParamField>

### initialize

```rust theme={null}
async fn initialize(&self) -> anyhow::Result<()>
```

Initializes the module. Called after creation and before the module is used.

<ParamField path="return" type="anyhow::Result<()>">
  Returns Ok(()) on success or an error
</ParamField>

## Optional Methods

### make\_module

```rust theme={null}
fn make_module(
    engine: Arc<Engine>,
    config: Option<Value>
) -> ModuleFuture
```

Helper method to create a module future. Has a default implementation that calls `create`.

<ParamField path="engine" type="Arc<Engine>" required>
  Reference to the iii engine instance
</ParamField>

<ParamField path="config" type="Option<Value>">
  Optional JSON configuration for the module
</ParamField>

<ParamField path="return" type="ModuleFuture">
  A pinned future that resolves to a module instance
</ParamField>

### start\_background\_tasks

```rust theme={null}
async fn start_background_tasks(
    &self,
    _shutdown: tokio::sync::watch::Receiver<bool>,
) -> anyhow::Result<()>
```

Starts any background tasks required by the module. Default implementation does nothing.

<ParamField path="shutdown" type="tokio::sync::watch::Receiver<bool>" required>
  Shutdown signal receiver to gracefully stop background tasks
</ParamField>

<ParamField path="return" type="anyhow::Result<()>">
  Returns Ok(()) on success or an error
</ParamField>

### destroy

```rust theme={null}
async fn destroy(&self) -> anyhow::Result<()>
```

Cleans up module resources during shutdown. Default implementation logs and returns Ok.

<ParamField path="return" type="anyhow::Result<()>">
  Returns Ok(()) on success or an error
</ParamField>

### register\_functions

```rust theme={null}
fn register_functions(&self, engine: Arc<Engine>)
```

Registers the module's functions with the engine. Usually overridden by the `#[service]` macro.

<ParamField path="engine" type="Arc<Engine>" required>
  Reference to the iii engine instance for function registration
</ParamField>

## Implementation Example

```rust theme={null}
use std::sync::Arc;
use async_trait::async_trait;
use serde_json::Value;
use iii::{
    engine::Engine,
    modules::module::Module,
};

#[derive(Clone)]
pub struct KvServer {
    storage: Arc<BuiltinKvStore>,
}

#[async_trait]
impl Module for KvServer {
    fn name(&self) -> &'static str {
        "KV Server"
    }

    async fn create(
        _engine: Arc<Engine>,
        config: Option<Value>,
    ) -> anyhow::Result<Box<dyn Module>> {
        let storage = BuiltinKvStore::new(config);
        let storage = Arc::new(storage);
        Ok(Box::new(KvServer { storage }))
    }

    fn register_functions(&self, engine: Arc<Engine>) {
        // Usually generated by #[service] macro
        self.register_functions(engine);
    }

    async fn initialize(&self) -> anyhow::Result<()> {
        Ok(())
    }
}
```

## Related Types

### ModuleFuture

```rust theme={null}
type ModuleFuture = Pin<Box<dyn Future<Output = anyhow::Result<Box<dyn Module>>> + Send>>;
```

A pinned boxed future that resolves to a Module instance.

## See Also

* [QueueAdapter](/api/traits/queue-adapter) - Trait for queue adapters
* [StreamAdapter](/api/traits/stream-adapter) - Trait for stream adapters
* [Custom Modules](/modules/custom-modules) - Guide to building custom modules