> ## 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.

# Architecture Overview

> Understanding Home Assistant's core architectural components and design principles

Home Assistant is built on a robust event-driven architecture that enables flexible home automation. The core consists of several interconnected components that work together to manage state, process events, and execute services.

## Core Components

The architecture is centered around four primary systems:

<CardGroup cols={2}>
  <Card title="HomeAssistant Core" icon="cube" href="/architecture/core">
    The central hub that coordinates all operations and manages the event loop
  </Card>

  <Card title="Event System" icon="bolt" href="/architecture/event-system">
    Event-driven communication enabling loose coupling between components
  </Card>

  <Card title="State Machine" icon="database" href="/architecture/state-machine">
    Centralized storage and management of all entity states
  </Card>

  <Card title="Service Registry" icon="list" href="/architecture/service-calls">
    Registration and execution of callable services across domains
  </Card>
</CardGroup>

## Architectural Principles

### Event-Driven Design

Home Assistant uses an event-driven architecture where components communicate through events rather than direct function calls. This provides:

* **Loose coupling** between components
* **Asynchronous operation** for better performance
* **Extensibility** allowing easy addition of new features

### Async-First Approach

The entire core runs on Python's `asyncio` event loop, providing:

```python homeassistant/core.py theme={null}
class HomeAssistant:
    def __init__(self, config_dir: str) -> None:
        """Initialize new Home Assistant object."""
        self.data = HassDict()
        self.loop = asyncio.get_running_loop()
        self.bus = EventBus(self)
        self.services = ServiceRegistry(self)
        self.states = StateMachine(self.bus, self.loop)
```

<Note>
  All core operations are designed to be non-blocking, allowing thousands of entities and automations to run concurrently without performance degradation.
</Note>

## Component Interaction Flow

<Steps>
  <Step title="State Change Occurs">
    A device or integration updates the state of an entity through the State Machine.
  </Step>

  <Step title="Event Fired">
    The State Machine fires a `state_changed` event on the Event Bus.
  </Step>

  <Step title="Listeners Notified">
    All registered listeners (automations, scripts, integrations) receive the event.
  </Step>

  <Step title="Service Calls Executed">
    Listeners may call services through the Service Registry to trigger actions.
  </Step>
</Steps>

## Core State Lifecycle

Home Assistant progresses through several states during its lifecycle:

```python homeassistant/core.py theme={null}
class CoreState(enum.Enum):
    """Represent the current state of Home Assistant."""
    
    not_running = "NOT_RUNNING"
    starting = "STARTING"
    running = "RUNNING"
    stopping = "STOPPING"
    final_write = "FINAL_WRITE"
    stopped = "STOPPED"
```

### Startup Sequence

The bootstrap process (defined in `homeassistant/bootstrap.py`) follows a staged approach:

<Info>
  **Stage 0**: Core integrations (logging, frontend, recorder)\
  **Stage 1**: Discovery integrations (bluetooth, DHCP, SSDP, USB)\
  **Stage 2**: All remaining integrations from configuration
</Info>

## Thread Safety

Home Assistant enforces strict thread safety rules:

```python homeassistant/core.py theme={null}
def verify_event_loop_thread(self, what: str) -> None:
    """Report and raise if we are not running in the event loop thread."""
    if self.loop_thread_id != threading.get_ident():
        from .helpers import frame
        frame.report_non_thread_safe_operation(what)
```

<Warning>
  All state changes, event firing, and service calls must occur within the event loop thread. Use `run_callback_threadsafe` when calling from external threads.
</Warning>

## Job Execution System

Home Assistant uses a sophisticated job execution system to handle different types of callables:

```python homeassistant/core.py theme={null}
class HassJobType(enum.Enum):
    """Represent a job type."""
    
    Coroutinefunction = 1  # async def functions
    Callback = 2           # @callback decorated functions
    Executor = 3           # Regular blocking functions
```

* **Coroutine functions**: Run directly in the event loop
* **Callbacks**: Executed immediately without task creation overhead
* **Executor jobs**: Run in a thread pool to avoid blocking

## Context Tracking

Every event, state change, and service call is associated with a Context:

```python homeassistant/core.py theme={null}
class Context:
    """The context that triggered something."""
    
    def __init__(self, user_id: str | None = None, 
                 parent_id: str | None = None,
                 id: str | None = None) -> None:
        self.id = id or ulid_now()
        self.user_id = user_id
        self.parent_id = parent_id
```

Contexts enable:

* Tracking which user triggered an action
* Following chains of automation executions
* Debugging complex automation flows

## Performance Optimizations

The architecture includes several performance optimizations:

<Tip>
  **Eager task creation**: Tasks start executing immediately without scheduler overhead\
  **Cached properties**: Expensive computations are cached using `@cached_property`\
  **Direct dict access**: Internal code bypasses public APIs for speed\
  **Event filtering**: Listeners can filter events before job creation
</Tip>

## Next Steps

Explore each core component in detail:

* [HomeAssistant Core](/architecture/core) - The central coordinator
* [Event System](/architecture/event-system) - Event-driven communication
* [State Machine](/architecture/state-machine) - State management
* [Service Calls](/architecture/service-calls) - Service execution