Adopting App Intents to support system experiences

At a glance

Project structure

AppIntentsTravelTracking/
├── AppIntentsTravelTracking/      # host app and views
├── TravelGalleryWidget/           # widget extension
└── TravelTrackingShared/
    └── Sources/
        ├── TravelTrackingCore/
        ├── TravelTrackingIntents/
        └── TravelTrackingSnippets/

Package dependencies point inward: views/targets may depend on shared libraries, while Core never imports the app target.

Overall architecture

flowchart LR
    App["Host app"] --> Snippets["TravelTrackingSnippets"]
    App --> Intents["TravelTrackingIntents"]
    App --> Core["TravelTrackingCore"]
    Widget["Widget extension"] --> Intents
    Widget --> Core
    Snippets --> Intents
    Intents --> Core
    Core --> Store["SharedDataStore / app group"]
    App --> DI["AppDependencyManager"]
    Widget --> DI2["Process-local dependency registry"]

Reference code

AppIntentsTravelTracking/TravelTrackingShared/Package.swift:21 — the package manifest enforces the layers (abridged).

products: [
    .library(name: "TravelTrackingCore", targets: ["TravelTrackingCore"]),
    .library(name: "TravelTrackingIntents", targets: ["TravelTrackingIntents"]),
    .library(name: "TravelTrackingSnippets", targets: ["TravelTrackingSnippets"])
],
targets: [
    .target(name: "TravelTrackingCore"),
    .target(name: "TravelTrackingIntents", dependencies: ["TravelTrackingCore"]),
    .target(name: "TravelTrackingSnippets", dependencies: ["TravelTrackingIntents"])
]

Ownership and state

classDiagram
    AppIntentsTravelTrackingApp *-- ModelData : State
    AppIntentsTravelTrackingApp *-- Navigator : State
    TravelGalleryWidgetBundle *-- ModelData : widget process
    ModelData o-- SharedDataStore : singleton per process
    SharedDataStore *-- UserDefaults : app-group suite
    SharedDataStore *-- Mutex
    AppIntent --> ModelData : injected
    WidgetProvider --> SharedDataStore : reads index

Ownership evidence

AppIntentsTravelTracking/TravelTrackingShared/Sources/TravelTrackingCore/Persistence/SharedDataStore.swift:50 — the process-local singleton owns synchronized access to shared defaults.

public final class SharedDataStore: Sendable {
    public static let shared = SharedDataStore()
    public static let suiteName =
        "group.com.example.apple-samplecode.AppIntentsTravelTracking"

    nonisolated(unsafe) private let defaults: UserDefaults
    private let lock = Mutex<Void>(())
}

ModelData is the in-memory mutation owner. The store shares encoded values, not object identity, across the app and widget processes.

Class and protocol design

Core owns models/persistence; Intents owns public entities, queries, intents, and Navigator; Snippets owns interactive intent flows and their views. Types adopt specialized framework contracts such as IndexedEntity, Transferable, AppIntentTimelineProvider, and UndoableIntent. LandmarkEntityQuery combines EntityQuery, EntityStringQuery, EnumerableEntityQuery, and IndexedEntityQuery at AppIntentsTravelTracking/TravelTrackingShared/Sources/TravelTrackingIntents/Entities/LandmarkEntity.swift:130.

Access control

The prevalence of public is evidence of true library boundaries, unlike target-only samples.

Logic ownership and placement

Design patterns

Naming conventions

• Module names encode dependency purpose: Core, Intents, Snippets.
• System types use precise role suffixes (Entity, Query, Intent, Provider, TimelineEntry).
• Mutation APIs use domain verbs (setLandmarkFavorite, setTags, applySavedState).

Architecture takeaways

• Use package targets when app and extension genuinely need shared compiled contracts.
• Share compact persisted values across processes, never assumptions about singleton identity.
• Keep system schema adapters outside Core domain models when they add framework dependencies.
• Register dependencies independently in every executable process (AppIntentsTravelTracking/TravelGalleryWidget/TravelGalleryWidgetBundle.swift:13).

Source map

• Official Apple documentation