# Integration file structure

> The files of an integration, what each one does, and where Home Assistant looks for integrations.

Source: https://contributors.home-assistant.io/core/integrations/file-structure/

Every integration lives in a folder named after its [domain](https://contributors.home-assistant.io/glossary/domain/). The mobile app integration has the domain `mobile_app`, so all its files are in `mobile_app/`. Home Assistant finds most features of an integration by file name, so the names below matter.

## The required files

- `manifest.json`: describes the integration, its requirements, and how it can be discovered. See [the manifest](https://contributors.home-assistant.io/core/integrations/manifest/).
- `__init__.py`: the integration itself, with its setup functions. If the integration only offers a platform, this file can be limited to a docstring, like `"""The Mobile App integration."""`.

## Common files

| File | What it holds |
| --- | --- |
| `const.py` | Constants, like `DOMAIN` |
| `config_flow.py` | The [config flow](https://contributors.home-assistant.io/core/integrations/config-flow/) and [options flow](https://contributors.home-assistant.io/core/integrations/options-flow/) |
| `coordinator.py` | The [data update coordinator](https://contributors.home-assistant.io/core/integrations/fetching-data/), if you subclass it |
| `entity.py` | A base entity class shared by your platforms |
| `light.py`, `sensor.py`, and so on | One [platform](https://contributors.home-assistant.io/glossary/platform/) per entity type. See [entities and platforms](https://contributors.home-assistant.io/core/entities/). |
| `strings.json` | All user-facing text, in English. See [make your strings translatable](https://contributors.home-assistant.io/translate/guides/developers/). |
| `icons.json` | Icons for entities, actions, and form sections |
| `services.yaml` | The description of the [actions](https://contributors.home-assistant.io/core/integrations/actions/) your integration registers |
| `quality_scale.yaml` | The status of each [quality scale](https://contributors.home-assistant.io/core/quality-scale/) rule for your integration |

## Platform files

Some files are integration platforms: Home Assistant loads them by name when the feature they provide is needed. You add the file, and the feature appears.

| File | Feature |
| --- | --- |
| `diagnostics.py` | [Diagnostics](https://contributors.home-assistant.io/core/integrations/diagnostics/) |
| `system_health.py` | [System health](https://contributors.home-assistant.io/core/integrations/system-health/) |
| `repairs.py` | [Repair flows](https://contributors.home-assistant.io/core/integrations/repairs/) |
| `reproduce_state.py` | [Reproduce state](https://contributors.home-assistant.io/core/integrations/reproduce-state/) for scenes |
| `significant_change.py` | [Significant change](https://contributors.home-assistant.io/core/integrations/significant-change/) |
| `backup.py` | [Backup agents and hooks](https://contributors.home-assistant.io/core/integrations/backup/) |
| `media_source.py` | [Media source](https://contributors.home-assistant.io/core/integrations/media-source/) |
| `application_credentials.py` | [Application credentials](https://contributors.home-assistant.io/core/integrations/oauth2/#application-credentials) for OAuth 2.0 |
| `device_trigger.py`, `device_condition.py`, `device_action.py` | [Device automations](https://contributors.home-assistant.io/core/integrations/device-automations/) |

## Where Home Assistant looks for integrations

Home Assistant looks for an integration when a config entry or `configuration.yaml` references its domain, or when another integration depends on it. It looks in two places:

- `<config directory>/custom_components/<domain>`
- `homeassistant/components/<domain>` (the integrations that ship with Home Assistant)

A custom integration with the same domain as a built-in one overrides it. That works, but the user then stops getting updates for that integration, and the manifest needs a `version`. Pick a unique domain for a custom integration unless you really mean to replace a built-in one.

## Brand images in custom integrations

A custom integration can ship its own icon and logo in a `brand/` folder inside the integration folder. Integrations in core put them in the [brands repository](https://github.com/home-assistant/brands) instead. See [integration brands and images](https://contributors.home-assistant.io/core/integrations/brands/).

## Tests

Tests live outside the integration folder, in `tests/components/<domain>/`. See [writing tests](https://contributors.home-assistant.io/core/development/tests/).