# home-assistant/android architecture

> Architecture diagram of the GitHub repository home-assistant/android, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/home-assistant/android
- Repository: https://github.com/home-assistant/android

## Overview

#### Purpose and build shape
Official Kotlin/Android client for connecting devices to Home Assistant servers, exposing the server UI plus native Android capabilities (sensors, notifications, controls, widgets, Assist, NFC, vehicle, and Wear OS). Gradle builds three principal apps: handset (`app`), Wear OS (`wear`), and Android Automotive (`automotive`), with shared domain/data infrastructure in `common`. Variant source sets distinguish `full` and `minimal` handset capabilities.
- `settings.gradle.kts`
- `app/build.gradle.kts`
- `common/build.gradle.kts`

#### Process entry points and composition
Android manifests register the application components; application classes initialize dependency injection and platform behavior. Handset startup enters `LaunchActivity`, which selects onboarding or the connected frontend. Additional OS-owned entry points include notification, Quick Settings, voice-assistant, controls, widget, and automotive services.
- `app/src/main/AndroidManifest.xml`
- `app/src/main/kotlin/io/homeassistant/companion/android/HomeAssistantApplication.kt`
- `app/src/main/kotlin/io/homeassistant/companion/android/launch/LaunchActivity.kt`

#### Server, authentication, and persistence boundary
`common` owns server selection, authenticated HTTP integration calls, TLS/trust handling, WebSocket protocol types, preferences, and Room persistence. Repository interfaces separate consumers from Retrofit/HTTP, socket, Android keystore, and database implementations. The Room database persists server/session metadata, sensor configuration, notifications, tiles, and widget state.
- `common/src/main/kotlin/io/homeassistant/companion/android/common/data/servers/ServerManager.kt`
- `common/src/main/kotlin/io/homeassistant/companion/android/common/data/authentication/AuthenticationRepository.kt`
- `common/src/main/kotlin/io/homeassistant/companion/android/database/AppDatabase.kt`

#### Primary Home Assistant data flow
After registration/authentication, feature layers use integration repositories for REST-style device registration, sensor updates, actions, and location updates; long-lived WebSocket repositories carry entity state, registry, template, conversation/Assist, Matter, and Thread responses/events. App-level `WebsocketManager` manages handset connectivity and reacts to Android lifecycle/network events.
- `common/src/main/kotlin/io/homeassistant/companion/android/common/data/integration/IntegrationRepository.kt`
- `common/src/main/kotlin/io/homeassistant/companion/android/common/data/websocket/WebSocketRepository.kt`
- `app/src/main/kotlin/io/homeassistant/companion/android/websocket/WebsocketManager.kt`

#### Handset experience: frontend and onboarding
The default experience is a native Compose shell around the Home Assistant web frontend. `FrontendViewModel` drives URL/session/UI state; handlers bridge WebView or JavaScript requests to native capabilities such as permissions, downloads, barcode scanning, dialogs, haptics, media, Bluetooth Improv provisioning, and Matter/Thread. First-run and server-change flows are a native Compose onboarding graph for discovery, manual server setup, connectivity/security, device naming, and location choices.
- `app/src/main/kotlin/io/homeassistant/companion/android/frontend/FrontendScreen.kt`
- `app/src/main/kotlin/io/homeassistant/companion/android/frontend/handler/FrontendMessageHandler.kt`
- `app/src/main/kotlin/io/homeassistant/companion/android/onboarding/serverdiscovery/HomeAssistantSearcher.kt`

#### Native capability pipelines
Sensor managers collect Android and device state; receivers/workers schedule updates, while `SensorRepository` serializes registration and uploads to Home Assistant. Native surfaces consume the same server/integration layer: Android Controls map HA entities to system controls; widgets store configuration locally and invoke HA actions; FCM receives server push notifications and routes actions. Assist combines voice-interaction services, audio strategies, Home Assistant assist pipelines, TTS, and optional bundled TensorFlow Lite wake-word models via a JNI/C++ module.
- `common/src/main/kotlin/io/homeassistant/companion/android/common/sensors/SensorUpdater.kt`
- `app/src/main/kotlin/io/homeassistant/companion/android/controls/HaControlsProviderService.kt`
- `app/src/main/kotlin/io/homeassistant/companion/android/assist/service/AssistVoiceInteractionService.kt`

#### Wear, automotive, and external infrastructure
Wear is a distinct Wear OS app with onboarding, home/entity views, complications, tiles, health sensors, phone data exchange, and FCM; it shares `common` persistence/protocol abstractions. Automotive contributes its own manifest while handset code contains the car-app service/screens. Full variants integrate Google Play services for Matter/Thread and Firebase Cloud Messaging; native wake-word execution uses CMake/JNI. CI runs GitHub Actions, including emulator E2E against a checked-in Home Assistant fixture.
- `wear/src/main/kotlin/io/homeassistant/companion/android/splash/SplashActivity.kt`
- `app/src/full/kotlin/io/homeassistant/companion/android/matter/MatterManagerImpl.kt`
- `microwakeword/src/main/cpp/MicroWakeWord_jni.cpp`

Main entry points: [`common/src/main/kotlin/io/homeassistant/companion/android/common/data/servers/ServerManager.kt`](https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/data/servers/ServerManager.kt) (Server & authentication), [`common/src/main/kotlin/io/homeassistant/companion/android/common/data/integration/IntegrationRepository.kt`](https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/data/integration/IntegrationRepository.kt) (Integration repository), [`common/src/main/kotlin/io/homeassistant/companion/android/common/data/websocket/WebSocketRepository.kt`](https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/data/websocket/WebSocketRepository.kt) (WebSocket repository), [`app/src/main/kotlin/io/homeassistant/companion/android/launch/LaunchActivity.kt`](https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/launch/LaunchActivity.kt) (Launch activity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build &amp; variants"]
  node_gradle["Gradle multi-app build"]
end

subgraph group_shared["Shared data layer"]
  node_server_auth["Server &amp; authentication<br/>[ServerManager.kt]"]
  node_auth_repository["Authentication repository"]
  node_integration["Integration repository<br/>REST repository"]
  node_websocket["WebSocket repository"]
  node_database[("Room app database<br/>persistence<br/>[AppDatabase.kt]")]
end

subgraph group_handset["Handset app"]
  node_manifests["Android component registry<br/>manifest"]
  node_application["Home Assistant application"]
  node_launch["Launch activity<br/>[LaunchActivity.kt]"]
  node_onboarding["Server onboarding<br/>compose flow"]
  node_frontend["Web frontend shell<br/>compose/webview<br/>[FrontendScreen.kt]"]
  node_frontend_bridge["Frontend native bridge<br/>message handler"]
  node_websocket_manager["Handset WebSocket manager<br/>connectivity manager"]
end

subgraph group_surfaces["Native surfaces"]
  node_sensors["Sensor update pipeline<br/>sensor service<br/>[SensorUpdater.kt]"]
  node_controls["Android controls<br/>system controls service"]
  node_assist["Assist voice service<br/>voice interaction service"]
end

subgraph group_platforms["Wear, automotive &amp; native"]
  node_wear["Wear OS app<br/>wear application<br/>[SplashActivity.kt]"]
  node_matter["Matter &amp; Thread integration<br/>full-variant manager"]
  node_wakeword{{"Micro wake-word JNI<br/>C++ JNI module"}}
end

node_home_assistant(("Home Assistant server<br/>external server"))

node_gradle -->|"builds handset"| node_application
node_gradle -->|"builds Wear app"| node_wear
node_manifests -->|"starts"| node_application
node_manifests -->|"registers"| node_launch
node_application -->|"initializes"| node_launch
node_launch -->|"unregistered server"| node_onboarding
node_launch -->|"connected session"| node_frontend
node_onboarding -->|"registers server"| node_server_auth
node_frontend -->|"native requests"| node_frontend_bridge
node_frontend -->|"uses session"| node_server_auth
node_frontend_bridge -->|"native actions"| node_integration
node_server_auth -->|"authenticates"| node_auth_repository
node_server_auth -->|"persists sessions"| node_database
node_auth_repository -->|"authentication"| node_home_assistant
node_integration -->|"REST calls"| node_home_assistant
node_websocket_manager -->|"maintains connection"| node_websocket
node_websocket -->|"events and responses"| node_home_assistant
node_sensors -->|"uploads state"| node_integration
node_controls -->|"entity state"| node_websocket
node_controls -->|"invokes actions"| node_integration
node_assist -->|"Assist conversations"| node_websocket
node_assist -->|"optional detection"| node_wakeword
node_matter -->|"Matter and Thread events"| node_websocket
node_wear -->|"shares server access"| node_server_auth
node_wear -->|"sensor and action calls"| node_integration

click node_gradle "https://github.com/home-assistant/android/blob/main/settings.gradle.kts"
click node_manifests "https://github.com/home-assistant/android/blob/main/app/src/main/AndroidManifest.xml"
click node_application "https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/HomeAssistantApplication.kt"
click node_launch "https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/launch/LaunchActivity.kt"
click node_onboarding "https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/onboarding/serverdiscovery/HomeAssistantSearcher.kt"
click node_frontend "https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/frontend/FrontendScreen.kt"
click node_frontend_bridge "https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/frontend/handler/FrontendMessageHandler.kt"
click node_websocket_manager "https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/websocket/WebsocketManager.kt"
click node_server_auth "https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/data/servers/ServerManager.kt"
click node_auth_repository "https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/data/authentication/AuthenticationRepository.kt"
click node_integration "https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/data/integration/IntegrationRepository.kt"
click node_websocket "https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/data/websocket/WebSocketRepository.kt"
click node_database "https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/database/AppDatabase.kt"
click node_sensors "https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/sensors/SensorUpdater.kt"
click node_controls "https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/controls/HaControlsProviderService.kt"
click node_assist "https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/assist/service/AssistVoiceInteractionService.kt"
click node_wear "https://github.com/home-assistant/android/blob/main/wear/src/main/kotlin/io/homeassistant/companion/android/splash/SplashActivity.kt"
click node_matter "https://github.com/home-assistant/android/blob/main/app/src/full/kotlin/io/homeassistant/companion/android/matter/MatterManagerImpl.kt"
click node_wakeword "https://github.com/home-assistant/android/blob/main/microwakeword/src/main/cpp/MicroWakeWord_jni.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gradle toneBlue
class node_server_auth,node_auth_repository,node_integration,node_websocket,node_database toneAmber
class node_manifests,node_application,node_launch,node_onboarding,node_frontend,node_frontend_bridge,node_websocket_manager toneMint
class node_sensors,node_controls,node_assist toneRose
class node_wear,node_matter,node_wakeword toneIndigo
class node_home_assistant toneNeutral
```

## Components

### Build & variants

- [Gradle multi-app build](https://github.com/home-assistant/android/blob/main/settings.gradle.kts): build · Builds handset, Wear OS, automotive, and shared modules with full/minimal variants. · `settings.gradle.kts`

### Shared data layer

- [Server & authentication](https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/data/servers/ServerManager.kt): repository · Selects servers and manages authenticated sessions, TLS, and trust. · `common/src/main/kotlin/io/homeassistant/companion/android/common/data/servers/ServerManager.kt`
- [Authentication repository](https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/data/authentication/AuthenticationRepository.kt): repository · `common/src/main/kotlin/io/homeassistant/companion/android/common/data/authentication/AuthenticationRepository.kt`
- [Integration repository](https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/data/integration/IntegrationRepository.kt): REST repository · Registers devices and sends sensor, action, and location updates. · `common/src/main/kotlin/io/homeassistant/companion/android/common/data/integration/IntegrationRepository.kt`
- [WebSocket repository](https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/data/websocket/WebSocketRepository.kt): socket repository · Carries entity, registry, template, Assist, Matter, and Thread events. · `common/src/main/kotlin/io/homeassistant/companion/android/common/data/websocket/WebSocketRepository.kt`
- [Room app database](https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/database/AppDatabase.kt): persistence · Stores server/session metadata and native feature state. · `common/src/main/kotlin/io/homeassistant/companion/android/database/AppDatabase.kt`

### Handset app

- [Android component registry](https://github.com/home-assistant/android/blob/main/app/src/main/AndroidManifest.xml): manifest · Registers app and OS-owned Android entry points. · `app/src/main/AndroidManifest.xml`
- [Home Assistant application](https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/HomeAssistantApplication.kt): application · Initializes dependency injection and platform behavior. · `app/src/main/kotlin/io/homeassistant/companion/android/HomeAssistantApplication.kt`
- [Launch activity](https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/launch/LaunchActivity.kt): activity · Selects onboarding or the connected frontend. · `app/src/main/kotlin/io/homeassistant/companion/android/launch/LaunchActivity.kt`
- [Server onboarding](https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/onboarding/serverdiscovery/HomeAssistantSearcher.kt): compose flow · Discovers and configures servers, security, device name, and location. · `app/src/main/kotlin/io/homeassistant/companion/android/onboarding/serverdiscovery/HomeAssistantSearcher.kt`
- [Web frontend shell](https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/frontend/FrontendScreen.kt): compose/webview · Hosts the Home Assistant frontend with native session state. · `app/src/main/kotlin/io/homeassistant/companion/android/frontend/FrontendScreen.kt`
- [Frontend native bridge](https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/frontend/handler/FrontendMessageHandler.kt): message handler · Bridges web requests to Android permissions and device capabilities. · `app/src/main/kotlin/io/homeassistant/companion/android/frontend/handler/FrontendMessageHandler.kt`
- [Handset WebSocket manager](https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/websocket/WebsocketManager.kt): connectivity manager · Maintains socket connectivity across lifecycle and network changes. · `app/src/main/kotlin/io/homeassistant/companion/android/websocket/WebsocketManager.kt`

### Native surfaces

- [Sensor update pipeline](https://github.com/home-assistant/android/blob/main/common/src/main/kotlin/io/homeassistant/companion/android/common/sensors/SensorUpdater.kt): sensor service · Collects Android state and serializes registration and uploads. · `common/src/main/kotlin/io/homeassistant/companion/android/common/sensors/SensorUpdater.kt`
- [Android controls](https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/controls/HaControlsProviderService.kt): system controls service · Maps Home Assistant entities to Android system controls. · `app/src/main/kotlin/io/homeassistant/companion/android/controls/HaControlsProviderService.kt`
- [Assist voice service](https://github.com/home-assistant/android/blob/main/app/src/main/kotlin/io/homeassistant/companion/android/assist/service/AssistVoiceInteractionService.kt): voice interaction service · Connects audio, Assist pipelines, TTS, and wake-word handling. · `app/src/main/kotlin/io/homeassistant/companion/android/assist/service/AssistVoiceInteractionService.kt`

### Wear, automotive & native

- [Wear OS app](https://github.com/home-assistant/android/blob/main/wear/src/main/kotlin/io/homeassistant/companion/android/splash/SplashActivity.kt): wear application · Provides Wear onboarding, entities, tiles, complications, sensors, and phone exchange. · `wear/src/main/kotlin/io/homeassistant/companion/android/splash/SplashActivity.kt`
- [Matter & Thread integration](https://github.com/home-assistant/android/blob/main/app/src/full/kotlin/io/homeassistant/companion/android/matter/MatterManagerImpl.kt): full-variant manager · Uses Google Play services in full handset variants. · `app/src/full/kotlin/io/homeassistant/companion/android/matter/MatterManagerImpl.kt`
- [Micro wake-word JNI](https://github.com/home-assistant/android/blob/main/microwakeword/src/main/cpp/MicroWakeWord_jni.cpp): C++ JNI module · Runs bundled TensorFlow Lite wake-word models. · `microwakeword/src/main/cpp/MicroWakeWord_jni.cpp`

### Other components

- **Home Assistant server**: external server · Provides frontend, authenticated APIs, WebSocket events, and Assist services.

## Connections

- Gradle multi-app build → Home Assistant application: builds handset
- Gradle multi-app build → Wear OS app: builds Wear app
- Android component registry → Home Assistant application: starts
- Android component registry → Launch activity: registers
- Home Assistant application → Launch activity: initializes
- Launch activity → Server onboarding: unregistered server
- Launch activity → Web frontend shell: connected session
- Server onboarding → Server & authentication: registers server
- Web frontend shell → Frontend native bridge: native requests
- Web frontend shell → Server & authentication: uses session
- Frontend native bridge → Integration repository: native actions
- Server & authentication → Authentication repository: authenticates
- Server & authentication → Room app database: persists sessions
- Authentication repository → Home Assistant server: authentication
- Integration repository → Home Assistant server: REST calls
- Handset WebSocket manager → WebSocket repository: maintains connection
- WebSocket repository → Home Assistant server: events and responses
- Sensor update pipeline → Integration repository: uploads state
- Android controls → WebSocket repository: entity state
- Android controls → Integration repository: invokes actions
- Assist voice service → WebSocket repository: Assist conversations
- Assist voice service → Micro wake-word JNI: optional detection
- Matter & Thread integration → WebSocket repository: Matter and Thread events
- Wear OS app → Server & authentication: shares server access
- Wear OS app → Integration repository: sensor and action calls
