Playola Radio iOS

Playola Radio is a streaming radio app for iOS featuring curated artist stations, traditional FM radio, and a rewards system for listening time.

Features

• 🎵 Stream curated artist radio stations and traditional FM stations
• 🎁 Earn rewards points based on listening time
• 🚗 Full CarPlay support
• 👤 User authentication (Apple Sign-In, Google Sign-In)
• 📊 Analytics tracking for listening sessions
• 🎨 Custom station artwork and branding

Architecture Overview

Core Technologies

• UI Framework: SwiftUI
• Architecture: MV (Model-View) with Swift's @Observable framework
• Dependency Injection: Dependencies
• State Management: Sharing
• Streaming: FRadioPlayer + PlayolaPlayer
• Analytics: Mixpanel
• CI/CD: GitHub Actions + CircleCI + Fastlane

Project Structure

PlayolaRadio/
├── Assets.xcassets/        # Images, colors, and app icons
├── CarPlay/                # CarPlay scene delegates
├── Config/                 # App configuration and secrets
├── Core/                   # Core business logic and services
│   ├── Analytics/          # Analytics tracking
│   ├── API/                # API client
│   ├── Audio/              # Audio streaming and playback
│   ├── Auth/               # Authentication services
│   ├── ListeningTracker/   # Listening session tracking
│   ├── Mail/               # Email services
│   └── Navigation/         # Navigation coordination
├── Extensions/             # Swift extensions and utilities
├── Models/                 # Data models
├── State/                  # State management
└── Views/                  # SwiftUI views and view models
    ├── Pages/              # Full-screen page views
    └── Reusable Components/# Shared UI components

Getting Started

Prerequisites

• Xcode 16.0+
• iOS 17.0+ deployment target
• Homebrew (for development tools)
• Ruby (for Fastlane)

Setup

1. Clone the repository

   git clone https://github.com/playola-radio/playola-radio-ios.git
   cd playola-radio-ios

2. Install Ruby dependencies

   bundle install

3. Configure secrets

   cp PlayolaRadio/Config/Secrets-Example.xcconfig PlayolaRadio/Config/Secrets-Local.xcconfig

   Edit Secrets-Local.xcconfig with your API keys and tokens. Edit Secrets-Staging.xcconfig with your API keys and tokens.

4. Install Git hooks

   ./.githooks/install-hooks.sh

5. Open in Xcode

   open PlayolaRadio.xcodeproj

6. Select scheme and run

   • Use PlayolaRadio scheme for production
   • Use PlayolaRadio-Local scheme for local development
   • Use PlayolaRadio-Staging scheme for staging environment

Development Conventions

Architecture Patterns

Models

All page models inherit from a base ViewModel class that provides Hashable conformance:

@MainActor
@Observable
class MyPageModel: ViewModel {
  @ObservationIgnored @Dependency(\.api) var api
  @ObservationIgnored @Dependency(\.analytics) var analytics
  
  // State properties
  var isLoading = false
  
  // Actions
  func viewAppeared() async {
    // Implementation
  }
}

Shared State

Use @Shared property wrapper for cross-view state:

@Shared(.auth) var auth
@Shared(.nowPlaying) var nowPlaying

Dependencies

Define dependencies using the @DependencyClient macro:

@DependencyClient
struct APIClient: Sendable {
  var getStations: @Sendable () async throws -> IdentifiedArrayOf<StationList>
}

Testing

Tests use XCTest with @MainActor for UI-related tests:

@MainActor
final class MyPageTests: XCTestCase {
  func testSomething() async {
    let model = MyPageModel()
    await model.viewAppeared()
    XCTAssertTrue(model.someState)
  }
}

Code Style

The project uses SwiftLint and swift-format for code consistency:

• SwiftLint rules are defined in .swiftlint.yml
• Code is automatically formatted on commit via Git hooks
• Force unwraps require SwiftLint exemption comments

Common Tasks

Running Tests

bundle exec fastlane test

Linting Code

bundle exec fastlane lint_code

Release Process

Starting a Release

1. Trigger workflow on develop with new version (e.g., 5.4.0)
   • Go to Actions → Prepare Release → Run workflow
   • Enter the new version number
   • Click the CircleCI link to monitor progress
2. git pull → Archive both schemes → Upload to TestFlight

Fixing Bugs During Release

1. Create fix branch off develop → merge fix to develop
2. Trigger workflow on develop (leave version blank - build auto-increments)
3. git pull → Archive → Upload
4. Repeat until satisfied

Finalizing the Release

1. Merge develop → main via PR
2. Tag (e.g., v5.4.0) is created automatically

Release CI Setup (One-Time)

The release workflow uses GitHub Actions to trigger CircleCI. Setup required:

1. CircleCI API Token → GitHub

• Go to CircleCI User Settings > Personal API Tokens
• Create a new token (name it "GitHub Actions")
• Copy the token
• Go to your GitHub repo → Settings → Secrets → Actions
• Add secret: CCI_TOKEN = (paste token)

2. Give CircleCI Write Access to Push Commits

• Go to CircleCI Project Settings > SSH Keys
• Click "Authorize with GitHub" under "User Key"
• This allows CircleCI to push the version bump commit

Key Components

Core Services

StationPlayer (Core/Audio/)

Central service managing radio playback state and FRadioPlayer integration.

ListeningTracker (Core/ListeningTracker/)

Tracks listening sessions for analytics and rewards calculation, persisting data locally.

APIClient (Core/API/)

Handles all network requests to the Playola backend.

AnalyticsClient (Core/Analytics/)

Manages analytics tracking through Mixpanel.

View Models

MainContainerModel (Views/Pages/MainContainer/)

Root view model managing app-wide navigation and sheet presentation.

Shared State Keys

• auth: User authentication state
• nowPlaying: Current playback information
• stationLists: Available radio stations
• activeTab: Current tab selection
• listeningTracker: Listening session tracking

Troubleshooting

Build Errors

1. Ensure all dependencies are resolved: Product → Update to Latest Package Versions
2. Clean build folder: Product → Clean Build Folder (⇧⌘K)
3. Delete derived data if needed

Secrets Configuration

Missing secrets will cause build failures. Ensure your Secrets-Local.xcconfig contains:

• MIXPANEL_TOKEN
• DEV_ENVIRONMENT
• API endpoints configuration

Contributing

1. Create a feature branch from develop
2. Make your changes following the coding conventions
3. Ensure all tests pass
4. Submit a pull request to develop

License

Proprietary - All rights reserved