Ha IOS Architecture
Developmentha-ios-architectureHa IOS Architecture is an Agent Skill for development published in the home-assistant/iOS repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/home-assistant/iOS/blob/HEAD/.agents/skills/ha-ios-architecture/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ha-ios-architecture, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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.xcodeprojdirectly (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 installinstalls 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:
// Sources/Shared/Environment/Environment.swift
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()
// ... many more dependencies
}
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.