Architecture

Architecture

Cadence is a sandboxed SwiftUI application using Swift 6 strict concurrency, Observation, SwiftData, AVFoundation, and native macOS media services.

flowchart LR
    UI[SwiftUI features] -->|intent| Model[CadenceAppModel]
    Model --> Store[LibraryStore]
    Store --> Repository[LibraryRepository]
    Repository --> SwiftData[SwiftData store]
    Model --> Import[ImportCoordinator]
    Import --> Managed[Cadence.library]
    Model --> Playback[PlaybackCoordinator]
    Playback --> PCM[PCM backend]
    Playback --> Native[Native backend]
    Playback --> System[Media keys and Control Center]

Loading

Application state

CadenceAppModel is the main-actor application orchestrator. Feature extensions divide library navigation, tags, collections, playlists, import, playback, lyrics, artwork, search, and contextual navigation. Views render observable state and call model intents; they do not mutate SwiftData, managed files, or audio engines directly.

Production starts through CadenceAppModel.production(librarySession:). The shipping target has no synthetic library. Test fixtures live under Tests/CadenceTests/Fixtures and cannot be activated by a release build.

Persistence

LibraryRepository owns the SwiftData container and versioned migrations. LibraryStore exposes paged catalog projections and derived counts. The schema stores tracks, albums, artists, artwork, tags, direct and inherited assignment state, playlists, smart collections, lyrics references, playback fields, and Trash metadata.

Schema changes require a new migration stage and temporary on-disk fixtures. Tests never run against the user's ~/Music/Cadence.library.

Concurrency

• UI-observable state stays on the main actor.
• Repositories, hashing, inspection, import work, and playback isolate mutable state behind explicit boundaries.
• Cross-boundary values conform to Sendable where required.
• Import and playback work propagate cancellation.

Project generation

project.yml is the source of truth. Cadence.xcodeproj is generated and committed for convenience:

xcodegen generate --spec project.yml

The canonical Icon Composer document is icon/Cadence.icon. One source carries shared square variants for macOS and future iOS targets plus the circular watchOS declaration. The current target compiles only macOS renditions.