Reorganize architecture section (#839)

docs/architecture/devices-and-services.md

@@ -0,0 +1,57 @@
+---
+title: "Entities: integrating devices & services"
+sidebar_label: "Introduction"
+---
+
+Integrations can represent devices & services in Home Assistant. The data points are represented as entities. Entities are standardized by other integrations like `light`, `switch`, etc. Standardized entities come with services for control, but an integration can also provide their own services in case something is not standardized.
+
+An entity abstracts away the internal working of Home Assistant. As an integrator you don't have to worry about how services or the state machine work. Instead, you extend an entity class and implement the necessary properties and methods for the device type that you're integrating.
+
+<img className='invertDark'
+  src='/img/en/architecture/integrating-devices-services.svg'
+  alt='Integrating devices & services' />
+
+<!--
+  https://docs.google.com/drawings/d/1oysZ1VMcPPuyKhY4tequsBWcblDdLydbWxlu6bH6678/edit?usp=sharing
+-->
+
+Configuration is provided by the user via a [Config Entry](../config_entries_index.md) or in special/legacy cases via [configuration.yaml](../configuration_yaml_index.md).
+
+The device integration (i.e. `hue`) will use this configuration to set up a connection with the device/service. It will forward the config entry (legacy uses discovery helper) to set up its entities in their respective integrations (light, switch). The device integration can also register their own services for things that are not made standardized. These services are published under the integration's domain, ie `hue.activate_scene`.
+
+The entity integration (i.e. `light`) is responsible for defining the abstract entity class and services to control the entities.
+
+The Entity Component helper is responsible for distributing the configuration to the platforms, forward discovery and collect entities for service calls.
+
+The Entity Platform helper manages all entities for the platform and polls them for updates if necessary. When adding entities, the Entity Platform is responsible for registering the entity with the device and entity registries.
+
+Integration Platform (i.e. `hue.light`) uses configuration to query the external device/service and create entities to be added. It is also possible for integration platforms to register entity services. These services will work on all entities of the device integration for the entity integration (i.e. all Hue light entities). These services are published under the device integration domain.
+
+## Entity interaction with Home Assistant Core
+
+The integration entity class that inherits from the entity base class is responsible for fetching the data and handle the service calls. If polling is disabled, it is also responsible for telling Home Assistant when data is available.
+
+<img className='invertDark'
+  src='/img/en/architecture/entity-core-interaction.svg'
+  alt='Entities interacting with core' />
+
+<!--
+  https://docs.google.com/drawings/d/12Z0t6hriYrQZ2L5Ou7BVhPDd9iGvOvFiGniX5sgqsE4/edit?usp=sharing
+-->
+
+The entity base class (defined by the entity integration)  is responsible for formatting the data and writing it to the state machine.
+
+The entity registry will write an `unavailable` state for any registered entity that is not currently backed by an entity object.
+
+## Entity data hierarchy
+
+<img className='invertDark'
+  style={{maxWidth: "200px"}}
+  src='/img/en/architecture/entity-data-hierarchy.svg'
+  alt='Entity hierarchy' />
+
+<!--
+  https://docs.google.com/drawings/d/1TorZABszaj3m7tgTyf-EMrheYCj3HAvwXB8YmJW5NZ4/edit?usp=sharing
+-->
+
+Delete, disable or re-enable any object and all objects below will be adjusted accordingly.

docs/architecture_components.md

@@ -1,29 +1,29 @@
 ---
-title: "Components Architecture"
-sidebar_label: "Components"
+title: "Integration Architecture"
+sidebar_label: "Integrations"
 ---
 
-Home Assistant can be extended with **components**. Each component is responsible for a specific domain within Home Assistant. Components can listen for or trigger events, offer services, and maintain states. Components are written in Python and can do all the goodness that Python has to offer. Out of the box, Home Assistant offers a bunch of [built-in components](https://www.home-assistant.io/integrations/).
+Home Assistant can be extended with **integrations**. Each integration is responsible for a specific domain within Home Assistant. Integrations can listen for or trigger events, offer services, and maintain states. Integrations are made up of a component (the base logic) and platforms (bits that integrate with other integrations). Integrations are written in Python and can do all the goodness that Python has to offer. Out of the box, Home Assistant offers a bunch of [built-in integrations](https://www.home-assistant.io/integrations/).
 
 <img class='invertDark'
 src='/img/en/architecture/component_interaction.png'
-alt='Diagram showing interaction between components and the Home Assistant core.' />
+alt='Diagram showing interaction between integrations and the Home Assistant core.' />
 
-There are two types of components within Home Assistant: components that interact with an Internet of Things domain, and components that respond to events that happen within Home Assistant. Read on to learn about each type!
+There are two types of integrations within Home Assistant: integrations that interact with an Internet of Things domain, and integrations that respond to events that happen within Home Assistant. Read on to learn about each type!
 
-## Components that interact with an Internet-of-Things domain
+## Integrations that interact with an Internet-of-Things domain
 
-These components track devices within a specific domain and consist of a core part and platform-specific logic. These components make their information available via the State Machine and the Event Bus. The components also register services in the Service Registry to expose control of the devices.
+These integrations track devices within a specific domain and consist of a core part and platform-specific logic. These integrations make their information available via the State Machine and the Event Bus. The integrations also register services in the Service Registry to expose control of the devices.
 
-For example, the built-in [`switch` component](https://www.home-assistant.io/components/switch/) is responsible for interaction with different types of switches. A platform provides support for a particular kind or brand of device. For example, a switch could use a WeMo or Orvibo platform and a light component might interact with the Hue or LIFX platform.
+For example, the built-in [`switch` component](https://www.home-assistant.io/integrations/switch/) is responsible for interaction with different types of switches. A platform provides support for a particular kind or brand of device. For example, a switch could use a WeMo or Orvibo platform and a light component might interact with the Hue or LIFX platform.
 
 If you want to add support for a new platform, check out the [add new platform section](creating_platform_index.md).
 
-## Components that respond to events that happen within Home Assistant
+## Integrations that respond to events that happen within Home Assistant
 
-These components provide small pieces of home automation logic or involve services that do common tasks within your house.
+These integrations provide small pieces of home automation logic or involve services that do common tasks within your house.
 
-For example, the [`device_sun_light_trigger` component](https://www.home-assistant.io/components/device_sun_light_trigger/) tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and people are home. The component uses logic like this:
+For example, the [`device_sun_light_trigger` component](https://www.home-assistant.io/integrations/device_sun_light_trigger/) tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and people are home. The component uses logic like this:
 
 ```text
 In the event that device 'Paulus Nexus 5' changes to the 'Home' state:
@@ -49,7 +49,7 @@ When we put all the different pieces of Home Assistant together, it's a close ma
 
 <img class='invertDark'
   src='/img/en/architecture/ha_full_architecture.png'
-  alt='Overview of the full Home Assistant architecture with a couple of loaded components and platforms'
+  alt='Overview of the full Home Assistant architecture with a couple of loaded integrations and platforms'
 />
 
-The platform logic for components uses third-party Python libraries to communicate with the devices. Through this, we can leverage some of the best libraries in the Python community.
+The platform logic for integrations uses third-party Python libraries to communicate with the devices. Through this, we can leverage some of the best libraries in the Python community.

docs/area_registry_index.md

@@ -1,6 +1,5 @@
 ---
 title: Area Registry
-sidebar_label: Introduction
 ---
 
 The area registry is a registry where Home Assistant keeps track of areas. An area represents a physical location for Home Assistant. It can be used to place devices in different areas.

docs/config_entries_index.md

@@ -1,6 +1,5 @@
 ---
 title: Config Entries
-sidebar_label: Introduction
 ---
 
 Config Entries are configuration data that are persistently stored by Home Assistant. A config entry is created by a user via the UI. The UI flow is powered by a [config flow handler](config_entries_config_flow_handler.md) as defined by the component. Config entries can also have an extra [options flow handler](config_entries_options_flow_handler.md), also defined by the component.

docs/core/entity.md

@@ -3,46 +3,9 @@ title: Entity
 sidebar_label: Introduction
 ---
 
-Each device is represented in Home Assistant as an entity. An entity abstracts away the internal working of Home Assistant. As an integrator you don't have to worry about how services or the state machine work. Instead, you extend an entity class and implement the necessary properties and methods for the device type that you're integrating.
+For a generic introduction of entities, see [entities architecture](../architecture/devices-and-services.md).
 
-<img class='invertDark'
-  src='/img/en/architecture/entities_architecture.png'
-  alt='Architecture Overview of Home Assistant' />
 
-## Configuration
-
-Configuration is provided by the [configuration.yaml file](configuration_yaml_index.md) or by a [Config Entry](config_entries_index.md).
-
-## Component
-
-Examples of components: `light`, `switch`.
-
-The component is responsible for defining the Abstract Entity Class and services to control the entities.
-
-## Entity Component
-
-The Entity Component is responsible for:
-
-- Distributing the configuration to the platforms
-- Forward config entries and discoveries
-- Collect entities for service calls
-- Optionally maintain a group of all entities
-
-## Entity Platform
-
-The Entity Platform manages all entities for the platform and polls them for updates if necessary.
-
-When adding entities, the Entity Platform will query the Entity Registry to make sure that the entities to be added have the correct entity IDs.
-
-## Entity Registry
-
-The [Entity Registry](entity_registry_index.md) will track entities and allows users to store extra settings for an entity.
-
-## Platform
-
-Examples of platforms: `light.hue`, `switch.wemo`.
-
-Platform uses configuration to query the external device/service and add entities to the entity platform.
 
 ## Basic implementation
 

docs/data_entry_flow_index.md

@@ -1,6 +1,5 @@
 ---
 title: Data Entry Flow
-sidebar_label: Introduction
 ---
 
 Data Entry Flow is a data entry framework that is part of Home Assistant. Data entry is done via data entry flows. A flow can represent a simple login form or a multi-step setup wizard for a component. A Flow Manager manages all flows that are in progress and handles creation of new flows.
@@ -309,10 +308,10 @@ class TestFlow(config_entries.ConfigFlow, domain=DOMAIN):
     VERSION = 1
     task_one = None
     task_two = None
-    
+
     async def _async_do_task(self, task):
         await task  # A task that take some time to complete.
-        
+
         # Continue the flow after show progress when the task is done.
         # To avoid a potential deadlock we create a new task that continues the flow.
         # The task must be completely done so the flow can await the task

docs/device_registry_index.md

@@ -1,6 +1,5 @@
 ---
 title: Device Registry
-sidebar_label: Introduction
 ---
 
 The device registry is a registry where Home Assistant keeps track of devices. A device is represented in Home Assistant via one or more entities. For example, a battery-powered temperature and humidity sensor might expose entities for temperature, humidity and battery level.
@@ -80,7 +79,7 @@ device_registry.async_get_or_create(
     connections={(dr.CONNECTION_NETWORK_MAC, config.mac)},
     identifiers={(DOMAIN, config.bridgeid)},
     manufacturer="Signify",
-    suggested_area="Kitchen",   
+    suggested_area="Kitchen",
     name=config.name,
     model=config.modelid,
     sw_version=config.swversion,

docs/entity_registry_index.md

@@ -1,6 +1,5 @@
 ---
 title: Entity Registry
-sidebar_label: Introduction
 ---
 
 The entity registry is a registry where Home Assistant keeps track of entities. Any entity that is added to Home Assistant which specifies the [`unique_id` attribute](/core/entity.md#generic-properties) will be registered in the registry.

sidebars.js

@@ -93,11 +93,18 @@ module.exports = {
       "auth_auth_provider",
       "auth_auth_module",
     ],
-    "Config Entries": ["config_entries_index"],
-    "Data Entry Flow": ["data_entry_flow_index"],
-    "Entity Registry": ["entity_registry_index", "entity_registry_disabled_by"],
-    "Device Registry": ["device_registry_index"],
-    "Area Registry": ["area_registry_index"],
+    Configuration: [
+      "config_entries_index",
+      "data_entry_flow_index"
+    ],
+    "Integrating devices & services": [
+      "architecture/devices-and-services",
+      "entity_registry_index",
+      "entity_registry_disabled_by",
+      "device_registry_index",
+      "area_registry_index"
+    ]
+
   },
   Core: {
     "Development Workflow": [