Skip to content

CLAUDE.md

Latest commit

 

History

History
98 lines (70 loc) · 3.7 KB

CLAUDE.md

File metadata and controls

98 lines (70 loc) · 3.7 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

PCVolumeControl is an iOS application that allows users to remotely control application audio volumes on a Windows PC. The app connects to a server running on the PC through a TCP connection and provides a UI to adjust volume levels for individual applications.

Architecture

  • Platform: iOS 17+ Swift app using SwiftUI
  • Architecture Pattern: MVVM (Model-View-ViewModel)
  • Networking: TCP socket communication using Apple's Network framework
  • Protocol: JSON-based protocol (version 7) for client-server communication

Key Components

  1. Connection Management:

    • MainViewModel.swift: Handles TCP socket connection, error handling, and data processing
    • Connection states: ready, preparing, failed, waiting, cancelled

  2. Data Models:

    • FullState: Server response with complete state information
    • Session: Represents an application with volume and mute state
    • Various update models for sending changes to the server

  3. UI Components:

    • MainView: Initial connection screen
    • SliderView: Volume controls for applications
    • ConnectingView: Connection status display

Development Workflow

Building and Running the App

  1. Open the project in Xcode:

    open PcVolumeControl.xcodeproj

  2. Select a target device or simulator

  3. Build and run the app using Xcode's run button or:

    ⌘+R

Running Tests

unit tests

Run this to execute all unit tests: xcodebuild test -scheme PcVolumeControl -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=26.0'

Dead Code Analysis

The project uses periphery to detect unused code.

  1. Install (one-time): brew install peripheryapp/periphery/periphery
  2. Run the scan from the repo root: periphery scan

In CI this runs as the periphery fastlane lane (bundle exec fastlane periphery), which adds --strict so the scan exits non-zero on findings. The .github/workflows/ci.yml workflow runs it on every push and pull request.

Configuration lives in the committed .periphery.yml; periphery scan reads it automatically. A clean run reports No unused code detected.. Notes:

  • retain_codable_properties: true keeps the encode-only wire DTOs in models/VolumeUpdateDTOs.swift from being flagged (their properties are written to JSON but never read back, which is not dead code).
  • report_exclude covers the widget scaffolding (AppIntent.swift, PcVolumeControlWidgetControl.swift, PcVolumeControlWidgetLiveActivity.swift) kept for planned widget work, and SnapshotHelper.swift, which is vendored verbatim from fastlane and must not be hand-edited.
  • The scan requires a single shared PcVolumeControl scheme. A stale per-user scheme under xcodeproj/xcuserdata/.../xcschemes/ creates a duplicate that makes periphery fail with "Scheme ... does not exist"; delete it (it is git-ignored and regenerated by Xcode).

Development Notes

  • The project is undergoing refactoring (branch: bill/refactor)
  • Recently migrated to SwiftUI from an older architecture
  • Pods dependencies have been removed
  • NEVER use emojis in the code, including in comments.

Protocol

The app communicates with the PC server using a JSON protocol:

  • Server → Client: Sends FullState with all devices and sessions information
  • Client → Server: Sends updates for:
    • Default device changes
    • Master volume/mute changes
    • Individual application volume/mute changes

Related Resources