From 6c183aea032c2be22721a0d7cd33638ff696aa25 Mon Sep 17 00:00:00 2001
From: James Magahern <james@magahern.com>
Date: Fri, 30 May 2025 17:17:18 -0700
Subject: [PATCH] adds CLAUDE.md

---
 CLAUDE.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..6779ac7
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,64 @@
+# 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
\ No newline at end of file