| name | ha-ios-architecture |
| description | Home Assistant iOS project layout, build setup, and the "World" dependency-injection pattern. Use when starting work in the repo, deciding where code lives across targets (App, Shared, Watch, CarPlay, Extensions), accessing dependencies through the global `Current`, or setting up dependencies and code signing. |
Architecture & Project Layout
Home Assistant for Apple Platforms is a native Swift companion app for Home Assistant home automation. The primary user interaction is through a WKWebView displaying the Home Assistant web frontend, with native features for notifications, sensors, location tracking, widgets, CarPlay, Apple Watch, and more.
- Language: Swift 5.8+
- Platforms: iOS, watchOS, macOS (Catalyst), CarPlay
- Build System: Xcode 26.2+, Swift Package Manager
- Project: Open
HomeAssistant.xcodeproj directly (dependencies are managed via Swift Package Manager)
Getting Started
Install Dependencies
bundle install
Third-party dependencies are managed via Swift Package Manager (SPM) and resolved automatically by Xcode. bundle install installs the Ruby tooling (Fastlane) used for linting, testing, and CI.
Code Signing (for device builds)
Create Configuration/HomeAssistant.overrides.xcconfig (git-ignored):
DEVELOPMENT_TEAM = YourTeamID
BUNDLE_ID_PREFIX = some.bundle.prefix
Project Structure
Sources/
├── App/ # Main iOS app target
├── Shared/ # Shared code across all platforms
├── Watch/ # watchOS-specific code
├── WatchApp/ # watchOS app target
├── MacBridge/ # macOS Catalyst bridge
├── CarPlay/ # CarPlay integration
├── Extensions/ # App Extensions (widgets, notifications, intents)
├── Improv/ # Improv BLE provisioning
├── PushServer/ # Push notification server communication
├── SharedPush/ # Shared push notification handling
├── SharedTesting/ # Shared testing utilities
├── Thread/ # Thread network support
├── Launcher/ # App launcher helper
Tests/
├── App/ # App-level tests
├── Shared/ # Shared module tests
├── UI/ # UI tests
├── Widgets/ # Widget tests
├── Mocks/ # Mock objects for testing
Configuration/ # Xcode build configuration files
fastlane/ # Fastlane automation (build, test, deploy)
Tools/ # Build tools, icon generation
The "World" Pattern (Dependency Injection)
This project uses the "World" pattern for dependency injection, inspired by Point-Free's "How to Control the World". This is the most important architectural concept in the codebase.
How It Works
A single global Current variable of type AppEnvironment holds all dependencies as mutable properties:
public var Current: AppEnvironment { ... }
public class AppEnvironment {
public var date: () -> Date = Date.init
public var calendar: () -> Calendar = { Calendar.autoupdatingCurrent }
public var servers: ServerManager = ServerManagerImpl()
public var clientEventStore: ClientEventStoreProtocol = ClientEventStore()
}
Usage in Production Code
Access dependencies through Current:
let now = Current.date()
let server = Current.servers.all.first
Current.Log.info("Something happened")
Usage in Tests
Override dependencies for testing:
Current.date = { Date(timeIntervalSince1970: 1000000) }
Current.servers = FakeServerManager()
⚠️ Critical Rule
Never assign to Current.* properties outside of test code. This is enforced by a custom SwiftLint rule that will fail CI. In production code, only read from Current.
Beta-Only Features
Current.isTestFlight is the only supported way to limit a feature to beta builds — no bespoke flags, build settings, or #if branches. Every gate must be paired with a draft PR that removes it; see the ha-ios-workflow-ci skill for the procedure.
Additional Resources
