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.
Settings Management: Server configuration stored in UserDefaults with validation through SettingsViewModel that tests connectivity on URL changes.

Data Flow

Settings: Server URL stored in UserDefaults, validated asynchronously via API calls
Real-time Updates: WebSocket connection provides live updates for playlist changes, playback state, and volume
API Integration: All server communication goes through the API struct using a fluent RequestBuilder pattern
State Management: Uses SwiftUI's @Observable pattern for reactive UI updates

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 - Add media URL to playlist
DELETE /playlist/{index} - Remove playlist item
POST /volume - Set volume level
WS /events - WebSocket for real-time updates

UI Structure

NowPlayingView: Playback controls and current track display
PlaylistView: Scrollable list of queued media with reorder/delete actions
AddMediaBarView: Input field for adding new media URLs
SettingsView: Server configuration with live validation

2.8 KiB Raw Blame History