# 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

1. **Settings**: Server URL stored in UserDefaults, validated asynchronously via API calls
2. **Real-time Updates**: WebSocket connection provides live updates for playlist changes, playback state, and volume
3. **API Integration**: All server communication goes through the `API` struct using a fluent `RequestBuilder` pattern
4. **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
```bash
# 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