OpenParable
Skip to content
← Back to skills

Ha IOS Architecture

Development
ha-ios-architecture

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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.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:

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

Additional Resources