93 lines
4.0 KiB
Markdown
93 lines
4.0 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.
|
|
- **Server.swift**: Represents individual jukebox servers with support for both manual configuration and Bonjour service discovery.
|
|
- **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:
|
|
```swift
|
|
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
|
|
```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
|
|
|
|
### 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 |