QueueCube/ios/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

QueueCube is a SwiftUI-based jukebox client application for iOS and macOS (via Mac Catalyst). It provides a frontend for controlling a server-based jukebox system that supports playlist management, favorites, and playback controls.

Architecture

Core Components

• API.swift: Central networking layer that handles all communication with the jukebox server. Includes REST API methods for playback control, playlist management, and WebSocket events for real-time updates.
• ContentView.swift: Main view controller containing the MainViewModel that coordinates between UI components and API calls. Handles WebSocket event processing and data flow.
• Server.swift: Represents individual jukebox servers with support for both manual configuration and Bonjour service discovery.
• ServerDiscovery.swift: Shared Bonjour browsing and bounded, cancellation-safe endpoint resolution for the app and share extension.
• RequestBuilder.swift: Shared extension-safe HTTP builder and error handling.
• SharePlayback.swift: Append once, select the new queue item, unpause, and verify playback using existing endpoints.
• Settings.swift: Manages multiple server configurations stored in UserDefaults with validation through SettingsViewModel that tests connectivity on URL changes.

Data Flow

1. Multiple Server Support: Array of Server objects stored in UserDefaults with selected server tracking
2. Settings: Server configurations validated asynchronously via API calls with live connectivity testing
3. Real-time Updates: WebSocket connection provides live updates for playlist changes, playback state, and volume
4. API Integration: All server communication goes through the API struct using a fluent RequestBuilder pattern
5. State Management: Uses SwiftUI's @Observable pattern for reactive UI updates

Request Builder Pattern

The API layer uses a fluent builder pattern for HTTP requests:

try await request()
    .path("/nowplaying")
    .json()

This provides type-safe, composable API calls with automatic error handling and connection state management.

Key Features

• Real-time sync: WebSocket events automatically refresh UI when server state changes
• Cross-platform: Supports iOS, iPadOS, and macOS via Mac Catalyst
• Settings validation: Live server connectivity testing with visual feedback
• Error handling: Connection state management with user-friendly error displays

Development Commands

Building

# Build for iOS Simulator
xcodebuild -project QueueCube.xcodeproj -scheme QueueCube -destination 'platform=iOS Simulator,name=iPhone 15' build

# Build for Mac Catalyst
xcodebuild -project QueueCube.xcodeproj -scheme QueueCube -destination 'platform=macOS,variant=Mac Catalyst' build

Running

• Open QueueCube.xcodeproj in Xcode
• Select target device (iOS Simulator or Mac)
• Run with Cmd+R

API Endpoints Reference

The server API includes these endpoints:

• GET /nowplaying - Current playback status
• GET /playlist - Current playlist items
• GET /favorites - User favorites
• POST /play, /pause, /skip, /previous - Playback controls
• POST /playlist - Append media URL (append-play starts only when idle)
• POST /skip/{index} - Select and play a zero-based playlist index; existing queue remains
• DELETE /playlist/{index} - Remove playlist item
• POST /volume - Set volume level
• WS /events - WebSocket for real-time updates

UI Structure

View Hierarchy

QueueCubeApp
└── ContentView (coordination layer)
    └── MainView (tab management)
        ├── PlaylistView (with embedded NowPlayingView)
        ├── FavoritesView (favorites management)
        └── SettingsView (server configuration)
            ├── ServerListSettingsView
            ├── AddServerView
            └── GeneralSettingsView

Key Views

• ContentView: Main coordinator that manages API instances and global state
• MainView: Tab-based navigation container with platform-specific adaptations
• PlaylistView: Scrollable list of queued media with reorder/delete actions, includes embedded NowPlayingView
• NowPlayingView: Playback controls and current track display
• AddMediaBarView: Input field for adding new media URLs to playlist
• SettingsView: Multi-server configuration with live validation and service discovery

Share extension

QueueCubeShare is embedded in iOS and Mac Catalyst builds. It reads an App Group settings snapshot and reuses the API/discovery code. See SHARE_EXTENSION.md for authentication limitations, queue/play failure semantics, signing setup, and focused tests.