64 lines
2.8 KiB
Markdown
64 lines
2.8 KiB
Markdown
|
# 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
|