Integration file structure

Every integration lives in a folder named after its 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.

• manifest.json: describes the integration, its requirements, and how it can be discovered. See the 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.""".

File	What it holds
const.py	Constants, like DOMAIN
config_flow.py	The config flow and options flow
coordinator.py	The data update coordinator, if you subclass it
entity.py	A base entity class shared by your platforms
light.py, sensor.py, and so on	One platform per entity type. See entities and platforms.
strings.json	All user-facing text, in English. See make your strings translatable.
icons.json	Icons for entities, actions, and form sections
services.yaml	The description of the actions your integration registers
quality_scale.yaml	The status of each quality scale rule for your integration

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
system_health.py	System health
repairs.py	Repair flows
reproduce_state.py	Reproduce state for scenes
significant_change.py	Significant change
backup.py	Backup agents and hooks
media_source.py	Media source
application_credentials.py	Application credentials for OAuth 2.0
device_trigger.py, device_condition.py, device_action.py	Device automations

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.

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 instead. See integration brands and images.

Tests live outside the integration folder, in tests/components/<domain>/. See writing tests.