Domain Layer

Core Services

Service	Responsibilities
`M2LibraryManager`	Track scanning, metadata extraction, artwork extraction, file deletion, cache warmup.
`M2PlaylistStore`	Playlist CRUD, custom covers, backup JSON, cover composition, migration safety.
`M2FavoritesStore`	Favorite ID set management and library projection.
`M2TrackAnalyticsStore`	Play/skip counters and affinity scoring pipeline.
`M2PlaybackManager`	Queue execution, repeat/shuffle, seek, now-playing metadata, remote command center.
`M2SleepTimerManager`	Timer lifecycle, remaining time updates, playback stop trigger, live activity sync.

Playback Engine Contracts

playTracks:startIndex: defines queue and active index atomically.
playNext/playPrevious respect repeat mode and shuffle history.
Progress notifications are emitted continuously while active.
Remote transport commands are enabled/disabled from queue state.

Playlist Store Rules

Playlist identifiers are stable and persisted.
Cover resolution order: custom cover -> collage from tracks -> placeholder artwork.
Desktop pinning references playlist identifiers, not index positions.
"Lovely songs" playlist is auto-maintained from analytics heuristics.

Favorites Rules

Favorites are persisted as normalized track identifiers.
Favorites view resolves current library snapshot each reload.
Desktop favorites page projects filtered set into 2 visual columns.

Analytics Heuristics

Inputs:
  playCount, skipCount, listen ratio, seek-to-end behavior

Outputs:
  score (affinity)
  sorted track ranking
  lovely-playlist eligibility decision

Storage Keys & Paths

Resource	Storage	Key / Path
Playlists	NSUserDefaults	`m2_playlists_v2`
Favorites	NSUserDefaults	`m2_favorites_v1`
Desktop pinned playlists	NSUserDefaults	`m2_desktop_pinned_playlists_v1`
Playlists backup	Application Support	`m2_playlists_backup_v1.json`
Track metadata cache	Application Support	`TrackMetadataCache/track_metadata_cache_v1.json`
Artwork cache	Application Support	`TrackMetadataCache/Artwork/*.jpg`
Playlist covers	Documents	`PlaylistCovers/`

Notification Bus

M2PlaybackStateDidChangeNotification
M2PlaybackProgressDidChangeNotification
M2PlaylistsDidChangeNotification
M2FavoritesDidChangeNotification
M2SleepTimerDidChangeNotification
M2DesktopPinPlaylistNotification
M2DesktopOpenPlaylistRequestNotification

Cache Strategy

Track metadata and artwork are persisted to reduce startup IO.
Playlist cover cache is invalidated on cover mutation.
Warmup in scene startup preloads hot objects for first-render speed.