# KRYZ Go! — Project Overview

> Mobile streaming client for KRYZ LP-FM 98.5 Mariposa community radio station.

## Tech Stack

| Layer | Technology |
|---|---|
| **Framework** | Flutter (Dart SDK ^3.11.5) |
| **Audio playback** | `just_audio` + `just_audio_background` + `audio_service` |
| **Network** | `http` (HTTP client for live-metadata API) |
| **Date/time** | `intl` + `timezone` |
| **Casting (Android)** | Google Cast framework (`play-services-cast-framework:22.1.0`) via Kotlin platform channel |
| **Casting (iOS)** | AirPlay via Swift platform channel |
| **Android Auto** | `MediaBrowserService` (Kotlin) + `androidx.media:1.7.0` |
| **iOS CarPlay** | Custom `CarPlaySceneDelegate` (Swift) |
| **Whitelabel build** | Python 3 + `Pillow` + `cairosvg` (`build_whitelabel.py`) |
| **Development** | VS Code Dev Container (Docker), `flutter_lints` |
| **Testing** | `flutter_test` (widget + unit tests) |

**Target platforms:** Android, iOS, macOS, Windows, Linux, Web.

### Key Dependencies

- `just_audio` (^0.10.5) — core audio playback engine
- `audio_service` (^0.18.18) — media session integration (lock screen, notifications)
- `audio_session` (^0.2.2) — audio focus / duck configuration
- `just_audio_background` (^0.0.1-beta.17) — background audio on mobile
- `http` (^1.5.0) — HTTP client for live-info metadata polling
- `timezone` (^0.10.1) — timezone-aware datetime handling
- `intl` (^0.20.2) — date/time formatting utilities
- `webview_flutter` (^4.13.0) — embedded WebView (declared but unused in current code path)
- `cupertino_icons` (^1.0.8) — iOS-style icon font

### Native Dependencies (Android)

- `play-services-cast-framework:22.1.0`
- `androidx.mediarouter:1.7.0`
- `androidx.media:1.7.0`
- Java/Kotlin target: Java 17

## Directory Structure

```
kryz-go-flutter/
├── lib/                              # Dart application source
│   ├── main.dart                     # Entry point + MaterialApp + MainPage UI
│   ├── kryz_audio_handler.dart       # Background audio handler (audio_service)
│   ├── streaming_audio_business_object.dart  # Audio playback controller
│   ├── casting_business_object.dart  # Cast/AirPlay state machine (platform channels)
│   ├── live_info_business_object.dart # Live metadata poller + data models
│   ├── live_info_panel.dart          # "Live Studio Feed" widget (now/next cards)
│   ├── track_card.dart               # Individual track display widget
│   ├── show_card.dart                # Show schedule display widget
│   ├── recently_played_list.dart     # Recently-played list widget (unused in current UI)
│   ├── app_theme_business_object.dart # Theme colors + light/dark ThemeData
│   ├── time_formatter.dart           # Timestamp parsing + timezone conversion
│   └── generated/                    # Auto-generated by build_whitelabel.py (not committed)
│       ├── app_config.dart           # Compile-time constants
│       └── theme_colors.dart         # Generated AppThemeColors
├── android/                          # Android native project
│   └── app/src/main/
│       ├── kotlin/.../MainActivity.kt      # Cast framework + MethodChannel bridge
│       ├── kotlin/.../KryzAutoMediaBrowserService.kt  # Android Auto media browser
│       ├── kotlin/.../CastOptionsProvider.kt          # Cast receiver config
│       ├── AndroidManifest.xml                   # App manifest + permissions
│       └── res/values/automotive_colors.xml      # Android Auto theming
├── ios/                              # iOS native project
│   └── Runner/
│       ├── AppDelegate.swift                     # Flutter engine + CarPlay setup
│       ├── SceneDelegate.swift                   # Scene lifecycle
│       └── CarPlaySceneDelegate.swift            # CarPlay template
├── macos/                            # macOS native project (Swift)
├── linux/                            # Linux native project (C++)
├── windows/                          # Windows native project (C++)
├── web/                              # Web entry point (index.html, manifest.json)
├── assets/icon/                      # App icon source
│   └── app_icon.png
├── test/                             # Dart tests
│   ├── widget_test.dart              # Basic widget smoke test
│   └── time_formatter_test.dart      # Timezone + formatting unit tests
├── build_whitelabel.py               # Whitelabel build script (Python)
├── requirements.txt                  # Python deps (Pillow, cairosvg)
├── pubspec.yaml                      # Flutter package manifest + Dart deps
├── analysis_options.yaml             # Dart linter config
├── README.md                         # Brief project docs
├── PROJECT_STRUCTURE.md              # Detailed architecture analysis
├── PROJECT_OVERVIEW.md               # This file — setup & onboarding guide
├── .devcontainer/                    # VS Code Dev Container config
└── theme.json                        # Station theme config (colors, images, URLs)
```

## Setup Instructions

### Prerequisites

- Flutter SDK (compatible with Dart ^3.11.5)
- Python 3.10+ (for whitelabel builds)
- Android Studio / Xcode for mobile builds (as applicable)
- Docker (optional, for VS Code Dev Container workflow)

### Quick Start

```bash
# 1. Clone the repository
git clone <repo-url> kryz-go-flutter
cd kryz-go-flutter

# 2. Check out the development branch
git checkout setup/project-onboarding

# 3. Install Flutter dependencies
flutter pub get

# 4. Generate whitelabel config (required before running)
#    You must have a theme.json in the project root.
pip install -r requirements.txt
python3 build_whitelabel.py

# 5. Run the app
flutter run                    # on connected device
flutter run -d chrome          # for web debugging
flutter run -d macos           # for macOS desktop
```

### Whitelabel Build

The app is fully re-brandable via a single `theme.json` file. This defines station name, callsign, frequency, stream URL, metadata endpoint, color palette, and embedded images.

```bash
# Full build (generates Dart configs, patches native manifests, generates icons)
python3 build_whitelabel.py --theme theme.json

# Dry run (preview what will change)
python3 build_whitelabel.py --theme theme.json --dry-run

# Skip native tool steps (Pillow/cairosvg not installed)
python3 build_whitelabel.py --no-tools
```

The script generates:
- `lib/generated/app_config.dart` — compile-time constants
- `lib/generated/theme_colors.dart` — light + dark theme colors
- `assets/icon/app_icon.png` — from embedded logo
- Patches to `AndroidManifest.xml`, `Info.plist`, `automotive_colors.xml`, and Kotlin sources

### Dev Container

Open the project in VS Code with the Dev Container extension. It provisions a Docker environment with Flutter and Python pre-installed. Post-create steps run `flutter pub get`, set up the Python venv, and install dependencies.

### Naming and Icons

```bash
# Rename the app across all platforms
dart run flutter_name_manager:rename_app --name "KRYZ Go!"

# Regenerate launcher icons
dart run flutter_launcher_icons
```

## Known Issues

1. **No Go backend despite repo name** — The repository is named `kryz-go-flutter` but contains only Flutter/Dart frontend code. The "Go" refers to the app brand name "KRYZ Go!", not the Go programming language.

2. **`webview_flutter` declared but unused** — The `webview_flutter` dependency is in `pubspec.yaml` but is not referenced anywhere in the current code path. Safe to remove if not planned for future use.

3. **`recently_played_list.dart` exists but is not wired into the UI** — The widget is built but not currently used in the main page layout.

4. **Minimal test coverage** — Only two test files exist (`widget_test.dart`, `time_formatter_test.dart`). No integration tests, mock API tests, or casting-specific tests are present.

5. **Hardcoded stream URL in audio handler** — The stream URL is loaded from `AppConfig` (generated by whitelabel), but the fallback and error-handling paths for stream disconnection are limited.

6. **Beta dependency** — `just_audio_background` is on a beta version (^0.0.1-beta.17), which may have stability issues on certain Android/iOS versions.

7. **Generated files not committed** — `lib/generated/` is not in the repository. Developers must run `build_whitelabel.py` with a `theme.json` before the app will compile.

8. **Android Auto cold-start race condition** — The startup sequence uses `unawaited()` calls that can cause issues if background media services initialize after an Android Auto cold start. A comment in `main.dart` acknowledges this.

## Architecture Overview

### Business Object Pattern

The codebase uses a "Business Object" naming convention for reactive state singletons (all extend `ChangeNotifier`):

| Business Object | Responsibility |
|---|---|
| `StreamingAudioBusinessObject` | Audio playback state (play/stop/buffering) |
| `CastingBusinessObject` | Cast/AirPlay connection state |
| `LiveInfoBusinessObject` | Live metadata + recently-played history |
| `AppThemeBusinessObject` | Theme color definitions |

### Data Flow

```
[Radio Station API] --HTTP--> [LiveInfoBusinessObject] --poll--> [UI: LiveInfoPanel]
                                                     --> [AudioHandler: updateMetadata]
                                                     --> [RecentlyPlayedList (runtime)]

[Station Stream URL] --stream--> [just_audio Player] --state--> [StreamingAudioBO] --> [UI: Play/Stop]

[Cast/AirPlay] <--platform channels--> [CastingBO] --> [UI: Cast button]
     |                                         |
     +--native--> MainActivity.kt / iOS native  +--> [stops local audio on handoff]
```

### Metadata Polling

- Polls the live-info API every 20 seconds
- Endpoint configured via `theme.json` or `KRYZ_LIVE_INFO_URL` env var
- Response parsed into `LiveInfoSnapshot`: current/next/previous tracks, show schedule, timezone
- Maintains a deduplicated "recently played" list (max 40 items) at runtime