Ha Android Architecture

HA Android Architecture

Use this skill when structuring a feature: which module and package it lives in, how its layers talk to each other, and how data is stored or fetched.

The full architecture documentation lives at https://developers.home-assistant.io/docs/android/architecture and https://developers.home-assistant.io/docs/android/ui_architecture.

Modules and Flavors

• :app (mobile), :automotive (reuses :app sources), :wear, :common (shared data layer, sensors, WebSocket, REST API), :testing-unit (shared test utilities, must stay independent from :common), :lint (custom lint rules), build-logic (Gradle convention plugins).
• :app and :automotive build in two flavors: full (Google Play Services: location, FCM, Wear communication) and minimal (FOSS). Keep code in the main source set flavor-agnostic whenever possible.
• Package by feature, not by layer: settings/ contains its ViewModels, UI, and repositories. Main feature areas under src/main/kotlin/io/homeassistant/companion/android/: assist/, sensors/, notifications/, settings/, onboarding/, thread/, matter/, qs/ (Quick Settings tiles), controls/ (device controls), launch/, vehicle/ (Android Auto/Automotive), widgets/, and frontend/.

Layers

Dependencies point downward only. From ui_architecture:

• ViewModel (UI layer): owns the screen state and coordination; see the ha-android-ui skill.
• Handler: logic that coordinates one or more managers. A handler is defined by depending on a manager; it may also use use cases and repositories, but never another handler — coordinate handlers in the ViewModel.
• Manager: owns the logic and in-memory state of exactly one feature concern. Depends only on repositories, use cases, and platform APIs — never on another manager.
• UseCase: a single reusable stateless operation, operator fun invoke(...), may depend on repositories only.
• Repository: single source of truth for one data source (API, Room DAO, preferences). No UI concerns, and no repository → repository dependencies.

Naming follows the block: *Repository + *RepositoryImpl, *UseCase, *Manager, *Handler, *ViewModel. DTOs are *Data.kt; domain models are named directly (User.kt).

Only split a block into interface + *Impl when it buys something real: multiple implementations exist (per flavor, fake for tests when a mock won't do), or the contract is public while the implementation stays internal to its module and is bound through DI. Otherwise a simple injectable class is preferred — don't create the pair by reflex.

Dependency Injection

• Use Hilt everywhere; never instantiate components manually.
• Scope blocks to how long their state must live: @ViewModelScoped for screen-session state, @Singleton for app-wide concerns. Stateful blocks injected in several places must be scoped so consumers share one instance.
• Never instantiate an @AndroidEntryPoint component (receiver, service) manually — Hilt field injection only happens through the framework lifecycle, so a hand-constructed instance crashes with UninitializedPropertyAccessException. Extract the shared logic into an injectable class or use an @EntryPoint interface instead.
• Prefer custom qualifier annotations over @Named:

@Qualifier
@Retention(AnnotationRetention.RUNTIME)
annotation class NamedKeyChain

@Inject @NamedKeyChain lateinit var keyChainRepository: KeyChainRepository

Storage

• Room for structured data, accessed through a repository via DAOs.
• For new storage use DataStore (encrypted); if it fits existing implementations, use the LocalStorage abstraction over SharedPreferences.
• Use EncryptedSharedPreferences for sensitive data. Encrypt data within the app whenever possible.