Integrating your photo app with Apple Intelligence

At a glance

Project structure

PhotosDomainExample/
├── AppIntents/
│   ├── Album/                  # Album entity, enum, and intents
│   ├── Asset/                  # Asset entity, filters, and intents
│   └── ShortcutsProvider.swift
├── Managers/                   # Media, image, location, navigation services
├── Model/                      # PhotoKit-backed Album and Asset wrappers
├── Views/                      # Album, asset, and favorites UI
└── PhotosDomainExample.swift   # Composition root

Feature-oriented App Intent folders sit beside framework-neutral manager and model folders. The app keeps system schema declarations separate from PhotoKit wrappers.

Overall architecture

flowchart LR
    Root["PhotosDomainExample"] --> Views["SwiftUI views"]
    Root --> Library["MediaLibrary"]
    Root --> Nav["NavigationManager"]
    Root --> DI["AppDependencyManager"]
    DI --> Intents["Photos schema intents"]
    DI --> Queries["Entity queries"]
    Intents --> Library
    Intents --> Nav
    Queries --> Library
    Library --> Models["Album / Asset wrappers"]
    Library --> PhotoKit["PHPhotoLibrary"]
    Library --> Spotlight["Core Spotlight"]
    Views --> Images["ImageManager actor"]

Reference code

PhotosDomainExample/PhotosDomainExample.swift:19 — the app gives views and intents the same library and navigation instances.

init() {
    let navigationManager = NavigationManager()
    let library = MediaLibrary()
    library.load()
    AppDependencyManager.shared.add(dependency: library)
    AppDependencyManager.shared.add(dependency: navigationManager)
    self.library = library
    self.navigationManager = navigationManager
}

The same objects are also placed in the SwiftUI environment. This keeps system-triggered work and foreground UI synchronized without an extension-specific store.

Ownership and state

classDiagram
    PhotosDomainExample *-- MediaLibrary : creates and retains
    PhotosDomainExample *-- NavigationManager : creates and retains
    MediaLibrary *-- Asset : collection snapshots
    MediaLibrary *-- Album : collection snapshots
    Asset o-- PHAsset : wraps
    Album o-- PHAssetCollection : wraps
    ImageManager *-- PHCachingImageManager : private cache
    AlbumQuery --> MediaLibrary : injected
    OpenAssetIntent --> NavigationManager : injected

Ownership evidence

PhotosDomainExample/Managers/MediaLibrary.swift:21 — collection mutation is restricted to the library facade.

private(set) var assets: [Asset] = []
private(set) var albums: [Album] = []

Class and protocol design

There is no app-defined repository protocol. Protocol-oriented design appears at framework seams (IndexedEntity, EntityQuery, OpenIntent, and DeleteIntent), while the concrete MediaLibrary is injected directly.

Access control

Reference code

PhotosDomainExample/Managers/MediaLibrary.swift:156 — off-main helpers stay both stateless and type-private.

// These run off the main actor so the library iteration and Photos
// change-blocks never block UI. They are pure helpers — they do not
// touch any actor-isolated state.

nonisolated private static func fetchAllPhotoAssets() async -> [PHAsset] {
    // ...
}

Logic ownership and placement

Design patterns

Naming conventions

• PhotoKit-backed domain wrappers use plain nouns (Asset, Album); system values append Entity.
• Long-lived capabilities append Manager: MediaLibrary is the deliberate domain-named exception and reads as a facade.
• Commands use verb-noun intent names (CreateAssetsIntent, OpenAlbumIntent, DeleteAssetsIntent).
• Mutation methods begin with verbs (create, delete, set, open); lookup methods use assets(for:) and albums(for:).
• App Intent folders are organized by schema noun, while view folders mirror UI features.

Architecture takeaways

• Share one observable framework facade between views and intents when both run in the app target.
• Use private(set) for collection snapshots whose writes must stay synchronized with an external framework and index.
• Keep collection-level operations in the library facade and item-level mutations on the PhotoKit-backed wrappers.
• Put mutable image caching behind an actor and keep navigation in a separate observable owner.
• Prefer framework protocol conformances for system integration; introduce custom protocols only when a real replacement seam is needed.

Source map

• Official Apple documentation