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

# Integration Overview

> Understanding Home Assistant integrations and their architecture

# Integration Overview

Integrations in Home Assistant are the building blocks that connect your home automation system with external devices, services, and platforms. This guide explains the architecture and core concepts behind Home Assistant integrations.

## What is an Integration?

An integration is a Python package that enables Home Assistant to communicate with a specific device, service, or protocol. Each integration lives in the `homeassistant/components/` directory and contains all the code needed to interact with that particular system.

<Info>
  **Example**: The MQTT integration (`homeassistant/components/mqtt/`) enables Home Assistant to communicate with devices using the MQTT protocol.
</Info>

## Integration Types

Home Assistant defines several integration types in the manifest, each serving a different purpose:

<CodeGroup>
  ```json manifest.json - Service Integration theme={null}
  {
    "domain": "mqtt",
    "name": "MQTT",
    "integration_type": "service",
    "iot_class": "local_push"
  }
  ```

  ```json manifest.json - System Integration theme={null}
  {
    "domain": "http",
    "name": "HTTP",
    "integration_type": "system",
    "iot_class": "local_push"
  }
  ```
</CodeGroup>

### Available Integration Types

* **entity** - Provides entity platforms for controlling devices
* **device** - Represents physical devices with multiple entities
* **hardware** - Interfaces with hardware (USB, GPIO, etc.)
* **helper** - Provides utility functions or services
* **hub** - Connects to a central hub that manages multiple devices
* **service** - Provides connectivity to external services
* **system** - Core Home Assistant functionality
* **virtual** - Provides virtual/computed entities

## Integration Architecture

Home Assistant uses a sophisticated loader system to discover and load integrations. Here's how it works:

<Steps>
  ### Discovery

  Home Assistant scans for integrations in two locations:

  1. **Built-in integrations**: `homeassistant.components`
  2. **Custom integrations**: `custom_components`

  ```python theme={null}
  # From loader.py
  PACKAGE_CUSTOM_COMPONENTS = "custom_components"
  PACKAGE_BUILTIN = "homeassistant.components"
  ```

  ### Loading

  The `Integration` class in `loader.py` handles loading integrations:

  ```python theme={null}
  class Integration:
      """An integration in Home Assistant."""
      
      def __init__(
          self,
          hass: HomeAssistant,
          pkg_path: str,
          file_path: pathlib.Path,
          manifest: Manifest,
      ) -> None:
          self.hass = hass
          self.pkg_path = pkg_path
          self.file_path = file_path
          self.manifest = manifest
  ```

  ### Setup

  Integrations can be set up in two ways:

  1. **YAML Configuration**: Traditional `async_setup()` method
  2. **Config Flow**: UI-based configuration with `async_setup_entry()`
</Steps>

## Core Concepts

### Platforms

Platforms are specific entity types that an integration can provide. Common platforms include:

* `light` - Light entities
* `switch` - Switch entities
* `sensor` - Sensor entities
* `climate` - Climate control entities
* `binary_sensor` - Binary sensor entities

```python theme={null}
# From const.py
class Platform(StrEnum):
    """Available entity platforms."""
    
    LIGHT = "light"
    SWITCH = "switch"
    SENSOR = "sensor"
    # ... more platforms
```

### Dependencies

Integrations can depend on other integrations to function:

```json theme={null}
{
  "domain": "mqtt",
  "dependencies": ["file_upload", "http"],
  "after_dependencies": ["hassio"]
}
```

<Note>
  **dependencies**: Must be loaded before this integration

  **after\_dependencies**: Should be loaded before this integration if present, but not required
</Note>

### Quality Scale

Integrations can achieve different quality levels:

* **platinum** - Highest quality, well-tested, excellent code
* **gold** - High quality, good test coverage
* **silver** - Good quality, basic tests
* **internal** - Core Home Assistant integrations
* **custom** - Custom integrations (default)

<Tip>
  When looking for examples to learn from, examine Platinum and Gold level integrations. The MQTT integration is a great example with a "platinum" quality scale.
</Tip>

## IoT Class

The IoT class describes how an integration communicates:

* `local_push` - Device pushes updates to Home Assistant locally
* `local_polling` - Home Assistant polls device locally
* `cloud_push` - Device pushes updates via cloud
* `cloud_polling` - Home Assistant polls cloud API
* `calculated` - Values are calculated, not from external sources

## Import Executor

For performance, integrations can be loaded in an executor thread:

```python theme={null}
@cached_property
def import_executor(self) -> bool:
    """Import integration in the executor."""
    # Defaults to True for better performance
    return self.manifest.get("import_executor", True)
```

<Warning>
  Set `"import_executor": false` only if your integration must be imported in the event loop. This is rare and should be avoided when possible.
</Warning>

## Single Config Entry

Some integrations should only have one configuration entry:

```json theme={null}
{
  "domain": "mqtt",
  "single_config_entry": true
}
```

This prevents users from accidentally creating multiple entries for the same integration.

## Preload Platforms

Certain platforms are automatically preloaded for faster startup:

```python theme={null}
BASE_PRELOAD_PLATFORMS = [
    "backup",
    "config_flow",
    "diagnostics",
    "logbook",
    "recorder",
    # ... more platforms
]
```

## Next Steps

<Card title="Creating Your First Integration" icon="code" href="/integrations/creating-components">
  Learn how to create a basic integration from scratch
</Card>

<Card title="Integration Manifest" icon="file-code" href="/integrations/integration-manifest">
  Understand the manifest.json file structure
</Card>

<Card title="Config Flow" icon="arrow-right-arrow-left" href="/integrations/config-flow">
  Implement UI-based configuration
</Card>

<Card title="Entity Platforms" icon="cube" href="/integrations/entity-platforms">
  Create entity platforms for your integration
</Card>