How realityexpander/fredsroadtripstoryteller works
Project Type and Purpose
• This is a Kotlin Multiplatform (KMP) Compose-based mobile application (“Fred’s Roadtrip Storyteller”) that runs natively on Android and iOS.
• It uses a single shared module for UI, domain, data, and service abstractions, with thin platform‐specific layers to integrate with Google Maps, location, text-to-speech, billing, notifications, etc.
High-Level Component Breakdown
A. Mobile Clients
• AndroidApp (androidApp/)
• iOSApp (iosApp/)
B. Shared KMP Core (shared/)
1. Common UI layer (Compose-based)
– Compose screens & UI components under shared/src/commonMain/kotlin/presentation
2. Domain layer
– Entities & use-cases (MarkersRepo, loadMarkers, loadMarkerDetails, AppSettings, billingAction)
3. Data layer
– HTTP client & network serializers (HttpClient, LatLongSerializerSurrogate)
– HTML parsing (ksoup-based parsers)
– Configuration resources (composeResources/appConfig.properties)
4. Platform service abstractions
– GPS location service (CommonGPSLocationService)
– Text-to-speech (CommonSpeech)
– Billing abstraction (CommonBilling)
– Navigation, email, feedback actions (openNavigationAction, sendEmailAction, sendFirebaseFeedback)
C. Platform-Specific Implementations
• AndroidMain (shared/src/androidMain)
– GPSForegroundNotificationService, Android TTS, PurchaseManager, NotificationActionReceiver
• iOSMain (shared/src/iosMain)
– iOS TTS, StoreKit wrapper, CocoaPods integration, EntitlementManager
D. External Systems & Services
– Google Maps SDK (Android & iOS)
– Google Play Billing / Apple StoreKit
– Firebase (feedback email)
– HTTP endpoints hosting marker HTML pages
Relationships & Data Flow
• AndroidApp and iOSApp each depend on the Shared module.
• At runtime:
1. UI layer invokes Domain use-cases (e.g., MarkersRepo.loadMarkers()).
2. Domain uses Data layer (HttpClient + HTML parsers) to fetch and parse marker data.
3. Parsed marker data flows back to UI, which displays it on a Compose Map component.
4. UI actions (tap marker, purchase, navigate, send feedback) call Shared service abstractions.
5. Those abstractions delegate to platform implementations in androidMain/iosMain, which call Google Maps SDK, location APIs, TTS engines, billing SDKs, notifications, etc.
• Background location tracking on Android uses a ForegroundService; on iOS it uses long-running location updates.
Architectural Patterns & Design Principles
• Layered (Presentation → Domain → Data → External)
• Single Source of Truth in shared module; no duplicate business logic.
• Platform adaptor pattern: abstractions in commonMain, delegates in androidMain/iosMain.
• MVU-style Compose UI: state flows down, events bubble up to domain/service layers.
• Dependency management via Gradle for Android, CocoaPods podspec for iOS.