From f3393348f72dfc20d370cc88951e780a5246894d Mon Sep 17 00:00:00 2001 From: robot Date: Fri, 31 Jul 2026 23:59:33 +0000 Subject: [PATCH 1/2] docs: add project structure and architecture analysis report - Map out complete folder structure with descriptions - Identify Flutter+Dart as primary stack (no Go backend) - Document all Dart source modules and their responsibilities - Document native platform code (Android Cast, iOS CarPlay) - Describe whitelabel build system (build_whitelabel.py + theme.json) - Document data flow between modules - List dependencies, dev environment, and test coverage --- PROJECT_STRUCTURE.md | 166 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 PROJECT_STRUCTURE.md diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md new file mode 100644 index 0000000..857de90 --- /dev/null +++ b/PROJECT_STRUCTURE.md @@ -0,0 +1,166 @@ +# KRYZ Go! — Project Structure & Architecture + +> Analysis of `kryz-go-flutter` on the `setup/project-onboarding` branch. + +## 1. Overview + +**KRYZ Go!** is a multi-platform **Flutter** mobile application for the KRYZ LP-FM 98.5 Mariposa community radio station. It streams live audio from the station, displays real-time metadata (now playing, upcoming show), and supports casting to external displays (Chromecast, Android Auto, iOS CarPlay/AirPlay). + +**Primary stack:** Flutter + Dart (frontend only). There is no Go backend in this repository — the project name "kryz-go-flutter" refers to the app name "KRYZ Go!", not a Go language backend. + +**Target platforms:** Android (including Android Auto), iOS (including CarPlay), macOS, Windows, Linux, and Web. + +## 2. Folder Structure + +``` +kryz-go-flutter/ +├── lib/ # Dart application source +│ ├── main.dart # App 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 (station name, stream URL, etc.) +│ └── theme_colors.dart # Generated AppThemeColors (light + dark) +├── 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 for whitelabel script (Pillow, cairosvg) +├── pubspec.yaml # Flutter package manifest + Dart deps +├── analysis_options.yaml # Dart linter config (flutter_lints) +├── README.md # Brief project docs +├── .devcontainer/ # VS Code Dev Container (Dockerfile + JSON) +└── theme.json # Station theme config (colors, images, stream URLs) +``` + +## 3. Key Configuration Files + +### pubspec.yaml +- **Package:** `kryz_go_flutter` +- **SDK:** Dart ^3.11.5 +- **Version:** 1.0.0+1 +- **Core dependencies:** + - `just_audio` (^0.10.5) — audio playback engine + - `just_audio_background` (^0.0.1-beta.17) — background audio support + - `audio_service` (^0.18.18) — media session integration (notifications, lock screen) + - `audio_session` (^0.2.2) — audio focus/Duck configuration + - `webview_flutter` (^4.13.0) — embedded WebView (unused in current code path) + - `http` (^1.5.0) — HTTP client for live-info API + - `intl` (^0.20.2) — date/time formatting + - `timezone` (^0.10.1) — timezone-aware datetime handling +- **Dev dependencies:** + - `flutter_name_manager` — rename app across platforms + - `flutter_launcher_icons` — generate platform-specific icons + - `flutter_lints` (^6.0.0) — recommended lint rules + +### Android build.gradle.kts +- **Namespace:** `com.example.kryz_go_flutter` +- **Java/Kotlin target:** Java 17 +- **Cast dependency:** `play-services-cast-framework:22.1.0` +- **Media router:** `androidx.mediarouter:1.7.0` +- **Media:** `androidx.media:1.7.0` + +## 4. Architecture + +### Entry Point +`lib/main.dart` initializes timezone data, then runs `MyApp` which creates two top-level business objects: `StreamingAudioBusinessObject` and `CastingBusinessObject`. The `MainPage` widget composes the full UI (header card + live info panel + playback controls). + +### Core Modules + +#### Audio Playback (`kryz_audio_handler.dart`, `streaming_audio_business_object.dart`) +- `KryzAudioHandler` extends `BaseAudioHandler` (from `audio_service`). It manages a `just_audio.AudioPlayer` instance that streams from a hard-coded `streamUrl` (loaded from `AppConfig`). +- Supports play/stop only (no seek — live stream). Keeps a persistent metadata refresh timer that polls the live-info API every 20 seconds. +- `StreamingAudioBusinessObject` wraps the handler, exposing a simplified `StreamingPlaybackStatus` enum and current track title/artist to the UI. + +#### Casting / Remote Playback (`casting_business_object.dart`) +- Communicates with native Android/iOS code through Flutter platform channels (`MethodChannel` + `EventChannel`). +- On Android: integrates with the Google Cast framework (Chromecast) and Android Auto. +- On iOS: integrates with AirPlay. +- Supports showing a device picker, starting a cast stream, stopping playback, and disconnecting. +- Handles the handoff from local playback to remote playback (stops `audio_service` when cast loads). + +#### Live Metadata (`live_info_business_object.dart`) +- Polls a metadata endpoint (configurable via `theme.json` or `KRYZ_LIVE_INFO_URL` env var) every 20 seconds. +- Parses the JSON response into `LiveInfoSnapshot` containing: + - `current`, `next`, `previous` track info (title, artist, album, timestamps) + - `currentShow`, `nextShow` (name, description, start/end times) + - `timezone`, `schedulerTime`, `sourceEnabled` +- Maintains a deduplicated "recently played" list (max 40 items) built at runtime. + +#### Theme / Whitelabeling (`build_whitelabel.py`, `app_theme_business_object.dart`) +- `theme.json` (not committed) defines station name, callsign, frequency, stream URL, metadata URL, color palette, and embedded images (logo, hero icon). +- `build_whitelabel.py` reads `theme.json` and generates: + - `lib/generated/app_config.dart` — compile-time constants + - `lib/generated/theme_colors.dart` — light + dark `AppThemeColors` + - `assets/icon/app_icon.png` — from embedded logo + - Patches `AndroidManifest.xml`, `Info.plist`, `automotive_colors.xml`, and Kotlin source files +- This design enables re-branding the entire app for different stations by changing a single JSON file. + +#### Native Platform Code +- **Android** (`MainActivity.kt`): Full Google Cast framework integration with session management, retry logic, media browser service for Android Auto, and platform channel bridging to Flutter. +- **iOS** (`AppDelegate.swift`, `CarPlaySceneDelegate.swift`): Flutter engine setup and CarPlay template scene delegate. +- **macOS/Linux/Windows**: Standard Flutter shell templates. + +### Data Flow + +``` +[Radio Station API] ──HTTP──> [LiveInfoBusinessObject] ──poll──> [UI: LiveInfoPanel] + └─> [KryzAudioHandler: updateMetadata] + └─> [RecentlyPlayedList (runtime)] + +[Station Stream URL] ──stream──> [just_audio Player] ──state──> [StreamingAudioBusinessObject] ──> [UI: Play/Stop buttons] + +[Cast/AirPlay] ◄──platform channels──> [CastingBusinessObject] ──> [UI: Cast button] + │ │ + └──native──> MainActivity.kt / iOS native └──> [stops local audio on handoff] +``` + +## 5. Business Object Pattern + +The codebase uses a "Business Object" naming convention for stateful singletons: +- `StreamingAudioBusinessObject` — audio playback state +- `CastingBusinessObject` — cast/AirPlay connection state +- `LiveInfoBusinessObject` — live metadata + recently-played history +- `AppThemeBusinessObject` — theme color definitions + +All extend `ChangeNotifier`, providing reactive state updates to Flutter widgets via `addListener`/`notifyListeners`. + +## 6. Development Environment + +- **Dev Container:** VS Code remote container with Flutter + Python venv. Extensions: Flutter, TypeScript. +- **Post-create:** `flutter pub get`, Python venv + deps install, Claude CLI install. +- **Build:** `flutter build ` or `flutter run ` for debug. +- **Whitelabel build:** `python3 build_whitelabel.py [--theme theme.json] [--dry-run] [--no-tools]` + +## 7. Test Coverage + +- `test/widget_test.dart` — basic smoke test verifying app title and playback buttons render. +- `test/time_formatter_test.dart` — comprehensive tests for timezone conversion, naive vs. explicit UTC timestamps, and time-window formatting. + +No integration tests, mock API tests, or casting-specific tests currently exist. -- 2.54.0 From d3ae2b6dc44595c47117c329c4181e2901e91542 Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Sat, 1 Aug 2026 00:17:18 +0000 Subject: [PATCH 2/2] docs: add PROJECT_OVERVIEW.md with setup instructions, tech stack, and known issues --- PROJECT_OVERVIEW.md | 211 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 211 insertions(+) create mode 100644 PROJECT_OVERVIEW.md diff --git a/PROJECT_OVERVIEW.md b/PROJECT_OVERVIEW.md new file mode 100644 index 0000000..11ce616 --- /dev/null +++ b/PROJECT_OVERVIEW.md @@ -0,0 +1,211 @@ +# 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 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 -- 2.54.0