Improve architecture docs (#850)

docs/architecture/core.md

@@ -0,0 +1,16 @@
+---
+title: Core Architecture
+sidebar_label: Core
+---
+
+The Home Assistant Core consists of four core parts. On top of this it includes a ton of helper classes to deal with common scenario's, like providing an entity or dealing with locations.
+
+- **Event Bus**: facilitates the firing and listening of events -- the beating heart of Home Assistant.
+- **State Machine**: keeps track of the states of things and fires a `state_changed` event when a state has been changed.
+- **Service Registry**: listens on the event bus for `call_service` events and allows other code to register services.
+- **Timer**: sends a `time_changed` event every 1 second on the event bus.
+
+<img class='invertDark'
+  alt='Overview of the Home Assistant core architecture'
+  src='/img/en/architecture/ha_architecture.svg'
+/>

docs/architecture_components.md

@@ -3,53 +3,34 @@ title: "Integration Architecture"
 sidebar_label: "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/).
+Home Assistant Core 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'
+src='/img/en/architecture/component-interaction.svg'
 alt='Diagram showing interaction between integrations and the Home Assistant core.' />
 
-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!
+Home Assistant distinguishes the following integration types:
 
-## Integrations that interact with an Internet-of-Things domain
+## Define an Internet of Things domain
 
-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.
+These integrations define a specific device category of Internet of Things devices in Home Assistant, like a light. It's up to the `light` integration to define what data is available in Home Assistant and in what format. It also provides services to control lights.
 
-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.
+For a list of defined domains, see [entities](./core/entity.md).
 
-If you want to add support for a new platform, check out the [add new platform section](creating_platform_index.md).
+To suggest a new domain, start a discussion in [the architecture repository](https://github.com/home-assistant/architecture/discussions). Make sure to show what data your proposed entity would include and how it can be controlled. Include examples from multiple brands.
 
-## Integrations that respond to events that happen within Home Assistant
+## Interact with external devices & services
 
-These integrations provide small pieces of home automation logic or involve services that do common tasks within your house.
+These integrations interact with external devices & services and make them available in Home Assistant via integrations that define IoT domains like `light`.  An example of such an integration is Philips Hue. Philips Hue lights are made available as light entities in Home Assistant.
 
-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:
+For more information, see [entity architecture](architecture/devices-and-services.md).
 
-```text
-In the event that device 'Paulus Nexus 5' changes to the 'Home' state:
-  If the sun has set and the lights are not on:
-    Turn on the lights
-```
+## Represent virtual/computed data points
 
-```text
-In the event that the combined state of all tracked devices changes to 'Not Home':
-  If the lights are on:
-    Turn off the lights
-```
+These integrations represent entities either based on virtual data, like the [`input_boolean` integration](https://www.home-assistant.io/integrations/input_boolean/), a virtual switch. Or they derive their data based on other data available in Home Assistant, like the [`template` integration](https://www.home-assistant.io/integrations/template/) or [`utility_meter` integration](https://www.home-assistant.io/integrations/utility_meter/).
 
-```text
-In the event of the sun setting:
-  If the lights are off and the combined state of all tracked device equals 'Home':
-    Turn on the lights
-```
+## Actions that can be triggered by the user or respond to events
 
-## The full picture
+These integrations provide small pieces of home automation logic that do common tasks within your house. The most popular one is the [`automation` integration](https://www.home-assistant.io/integrations/automation/), allowing users to create automations through a configuration format.
 
-When we put all the different pieces of Home Assistant together, it's a close match for the initial home automation overview sketch. The smart home AI has not been implemented yet, so it's not included in this picture.
-
-<img class='invertDark'
-  src='/img/en/architecture/ha_full_architecture.png'
-  alt='Overview of the full Home Assistant architecture with a couple of loaded integrations and platforms'
-/>
-
-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.
+It can also be more specific, like the [`flux` integration](https://www.home-assistant.io/integrations/flux/), which controls lights based on the sun setting.

docs/architecture_index.md

@@ -3,27 +3,17 @@ title: "Architecture"
 sidebar_label: "Introduction"
 ---
 
-Before we dive into the Home Assistant architecture, let's get a clear overview of the home automation landscape as a whole. This way, we can show how the different parts of Home Assistant fit into the picture.
+Home Assistant provides a platform for home control and home automation. Home Assistant is not just an application: it's an embedded system that provides an experience like other consumer off-the-shelf products: onboarding, configuration and updating is all done via an easy to use interface.
 
-For more information about each part in this overview, [check out our blog](https://www.home-assistant.io/blog/2014/12/26/home-control-home-automation-and-the-smart-home). Here's the tl;dr version of the blog:
-
-- Home Control is responsible for collecting information and controlling devices.
-- Home Automation triggers commands based on user configurations.
-- Smart Home triggers commands based on previous behavior.
+- The [operating system](operating-system.md) provides the bare minimal Linux environment to run Supervisor and Core.
+- The [Supervisor](supervisor.md) manages the operating system.
+- The [Core](architecture/core.md) interacts with the user, the supervisor and IoT devices & services.
 
 <img class='invertDark'
-  src='/img/en/architecture/home_automation_landscape.svg'
-  alt='Home Automation landscape'
+  src='/img/en/architecture/full.svg'
+  alt='Full picture of Home Assistant'
 />
 
-The Home Assistant core is responsible for Home Control. Home Assistant contains four parts which make this possible:
+## Running parts of the stack
 
-- **Event Bus**: facilitates the firing and listening of events -- the beating heart of Home Assistant.
-- **State Machine**: keeps track of the states of things and fires a `state_changed` event when a state has been changed.
-- **Service Registry**: listens on the event bus for `call_service` events and allows other code to register services.
-- **Timer**: sends a `time_changed` event every 1 second on the event bus.
-
-<img class='invertDark'
-  alt='Overview of the Home Assistant core architecture'
-  src='/img/en/architecture/ha_architecture.svg'
-/>
+Users have different requirements what they want from a home automation platform. That's why it is possible to run only part of the Home Assistant stack. For more information, see the [installation instructions](https://www.home-assistant.io/installation/).

docs/dev_101_hass.md

@@ -1,5 +1,6 @@
 ---
 title: "Hass object"
+sidebar_label: "Introduction"
 ---
 
 While developing Home Assistant you will see a variable that is everywhere: `hass`. This is the Home Assistant instance that will give you access to all the various parts of the system.
@@ -16,15 +17,20 @@ The Home Assistant instance contains four objects to help you interact with the
 | `hass.bus` | This is the EventBus. It allows you to trigger and listen for events. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.EventBus) |
 | `hass.services` | This is the ServiceRegistry. It allows you to register services. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.ServiceRegistry) |
 
+<img class='invertDark'
+  alt='Overview of the Home Assistant core architecture'
+  src='/img/en/architecture/ha_architecture.svg'
+/>
+
 ### Where to find `hass`
 
 Depending on what you're writing, there are different ways the `hass` object is made available.
 
-**Component**  
+**Component**
 Passed into `setup(hass, config)` or `async_setup(hass, config)`.
 
-**Platform**  
+**Platform**
 Passed into `setup_platform(hass, config, add_devices, discovery_info=None)` or `async_setup_platform(hass, config, async_add_devices, discovery_info=None)`.
 
-**Entity**  
+**Entity**
 Available as `self.hass` once the entity has been added via the `add_devices` callback inside a platform.

docs/dev_101_index.md

@@ -1,49 +0,0 @@
----
-title: "Development 101"
-sidebar_label: Introduction
----
-
-The goal of development 101 is to get you familiar with the basics of developing for Home Assistant. Before we start, please make sure you familiarize yourself with the [architecture](architecture_index.md).
-
-To get our code running inside Home Assistant we're going to create a custom component. The first step is to locate your config folder. You can find the path to your config folder by opening the Home Assistant frontend, click on the <img src='/img/dev-tools/about-icon.png' alt='service developer tool icon' class="inline" height="18px" />. It's the path after the text "Path to configuration.yaml".
-
-Inside your configuration directory create a new folder called `custom_components`. It might be that one already exists, that's fine too. This is the folder that Home Assistant will look at when looking for custom code.
-
-:::info
-The Home Assistant API has two variants: a synchronous and an asynchronous version (asyncio). This development course will focus on the synchronous version.
-:::
-
-To verify that everything is working correctly, let's create a small Hello World component. To do so, create a file called `hello_world.py` in your custom components folder. Copy paste the following content to it:
-
-```python
-# The domain of your component. Equal to the filename of your component.
-DOMAIN = "hello_world"
-
-
-def setup(hass, config):
-    """Setup the hello_world component."""
-    # States are in the format DOMAIN.OBJECT_ID.
-    hass.states.set("hello_world.Hello_World", "Works!")
-
-    # Return boolean to indicate that initialization was successfully.
-    return True
-```
-
-Last step is to add `hello_world:` entry to your `configuration.yaml` file.
-
-```yaml
-# Hello World component
-hello_world:
-```
-
-After running `hass`, we should see log entries stating that `hello_world` component was loaded. What is more, an additional state card will appear within the main panel.
-
-```log
-2018-04-03 21:44:20 INFO (MainThread) [homeassistant.loader] Loaded hello_world from custom_components.hello_world
-2018-04-03 21:44:20 INFO (MainThread) [homeassistant.setup] Setting up hello_world
-```
-
-<img
-  src='/img/en/frontend/hello-world-state-card.png'
-  alt='State card showing that Hello World component is working as intended.'
-/>

sidebars.js

@@ -85,7 +85,11 @@ module.exports = {
   Supervisor: ["supervisor", "supervisor/development", "supervisor/debugging"],
   // Old structure, still to move/migrate
   Architecture: {
-    Architecture: ["architecture_index", "architecture_components"],
+    Architecture: [
+      "architecture_index",
+      "architecture/core",
+      "architecture_components",
+    ],
     Authentication: [
       "auth_index",
       "auth_permissions",
@@ -93,18 +97,14 @@ module.exports = {
       "auth_auth_provider",
       "auth_auth_module",
     ],
-    Configuration: [
-      "config_entries_index",
-      "data_entry_flow_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"
-    ]
-
+      "area_registry_index",
+    ],
   },
   Core: {
     "Development Workflow": [
@@ -138,8 +138,7 @@ module.exports = {
       "creating_platform_code_review",
       "integration_quality_scale_index",
     ],
-    "Home Assistant Core 101": [
-      "dev_101_index",
+    "Accessing the Core": [
       "dev_101_hass",
       "dev_101_events",
       "dev_101_states",

static/_redirects

@@ -61,3 +61,4 @@
 /docs/internationalization_translation.html /docs/translations
 /docs/lovelace_custom_card /docs/frontend/custom-ui/lovelace-custom-card
 /docs/supervisor/developing /docs/supervisor/development
+/docs/dev_101_index /docs/dev_101_hass