Accelerating app interactions with App Intents

At a glance

Project structure

AppIntentsSampleApp/
├── AppIntentsSampleApp.swift
├── App Intents/
│   ├── Entities/
│   └── Workout Intents/
├── Model/                  # trail, account, navigation, activity managers
├── Views/
└── Utililty/

The app and watch targets share source membership; there is no separate extension target or library package.

Overall architecture

flowchart LR
    Root["AppIntentsSampleApp"] --> TrailManager["TrailDataManager"]
    Root --> Account["AccountManager"]
    Root --> Activity["ActivityTracker"]
    Root --> Navigation["NavigationModel"]
    Root --> Views["SwiftUI environment"]
    Root --> DI["AppDependencyManager"]
    DI --> Intents["App Intents"]
    DI --> Queries["Entity queries"]
    Queries --> Entity["TrailEntity"]
    Intents --> Navigation

Reference code

AppIntentsSampleApp/AppIntentsSampleApp.swift:19 — composition happens at the earliest non-UI-dependent launch path (abridged).

let trailDataManager = TrailDataManager.shared
let navigationModel = NavigationModel(
    selectedCollection: trailDataManager.nearMeCollection
)
let activityTracker = ActivityTracker.shared

AppDependencyManager.shared.add(dependency: trailDataManager)
AppDependencyManager.shared.add(dependency: navigationModel)
AppDependencyManager.shared.add(dependency: activityTracker)

Ownership and state

classDiagram
    AppIntentsSampleApp o-- TrailDataManager : shared
    AppIntentsSampleApp *-- NavigationModel : scene state
    AppIntentsSampleApp o-- AccountManager : shared
    AppIntentsSampleApp o-- ActivityTracker : shared
    ActivityTracker *-- Activity : history
    ActivityTracker *-- LiveWorkoutManager : watchOS only
    OpenFavorites --> NavigationModel : injected
    TrailEntityQuery --> TrailDataManager : injected

Ownership evidence

AppIntentsSampleApp/Model/ActivityTracker.swift:14 — one manager owns activity history and conditionally owns the watch implementation.

@Observable class ActivityTracker: ActivityTrackingActions, @unchecked Sendable {
    static let shared = ActivityTracker()
    private(set) var activityHistory: [Activity]
    private(set) var activityInProgress: Activity?
    private var liveWorkoutManager: ActivityTrackingActions?
}

Managers are the mutation authorities. Views receive them through SwiftUI environment; App Intents receive the same instances through App Intents dependency injection.

Class and protocol design

TrailEntity: AppEntity is deliberately separate from Trail, exposing only system-relevant data (AppIntentsSampleApp/App Intents/Entities/TrailEntity.swift:11). Intent structs adopt specialized framework protocols such as OpenIntent and StartWorkoutIntent. The private ActivityTrackingActions protocol at AppIntentsSampleApp/Model/ActivityTracker.swift:257 lets the cross-platform tracker substitute a watchOS HealthKit implementation without exposing that abstraction app-wide.

Access control

Logic ownership and placement

Design patterns

Naming conventions

• System entry points use verb-first names (OpenFavorites, SuggestTrails, StartTrailActivity).
• Framework roles use suffixes (Entity, EntityQuery, OptionsProvider, Manager, Tracker).
• Domain values remain singular (Trail, Activity); owning collections/managers use broader nouns.

Architecture takeaways

• Register intent dependencies before any code assumes a visible scene.
• Keep entity schemas separate when the app model contains expensive or irrelevant fields.
• Use one mutation owner for UI and system entry points.
• Treat the watch target as a platform specialization of shared architecture, not an extension process.

Source map

• Official Apple documentation