# realityexpander/fredsroadtripstoryteller architecture

> Architecture diagram of the GitHub repository realityexpander/fredsroadtripstoryteller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/realityexpander/fredsroadtripstoryteller
- Repository: https://github.com/realityexpander/fredsroadtripstoryteller

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Mobile Clients"
        AndroidApp["AndroidApp"]:::android
        iOSApp["iOSApp"]:::ios
    end

    %% Shared Core
    subgraph "Shared KMP Core" 
        direction TB
        subgraph "UI Layer"
            SharedUI["Compose UI (presentation)"]:::shared
        end
        subgraph "Domain Layer"
            MarkersRepo["MarkersRepo"]:::shared
            LoadMarkers["loadMarkers()"]:::shared
            LoadMarkerDetails["loadMarkerDetails()"]:::shared
            AppSettings["AppSettings"]:::shared
            BillingAction["billingAction"]:::shared
        end
        subgraph "Data Layer"
            HttpClient["HttpClient"]:::shared
            LatLongSerializer["LatLongSerializerSurrogate"]:::shared
            ParseMarkersHtml["parseMarkersPageHtml"]:::shared
            ParseDetailsHtml["parseMarkerDetailsPageHtml"]:::shared
            AppConfig["appConfig.properties"]:::shared
        end
        subgraph "Service Abstractions"
            GPSService["CommonGPSLocationService"]:::shared
            Speech["CommonSpeech"]:::shared
            BillingAbstraction["CommonBilling"]:::shared
            NavigationAction["openNavigationAction"]:::shared
            WebAction["openWebUrlAction"]:::shared
            EmailAction["sendEmailAction"]:::shared
            FeedbackAction["sendDeveloperFeedback"]:::shared
        end
    end

    %% Platform Implementations
    subgraph "Platform Implementations"
        direction TB
        subgraph "AndroidMain" 
            AGPSService["GPSForegroundNotificationService"]:::android
            AndroidTTS["AndroidTextToSpeech"]:::android
            PurchaseManager["ProductPurchaseAction"]:::android
            NotificationReceiver["NotificationActionBroadcastReceiver"]:::android
            ANavigation["openNavigationAction"]:::android
            AFeedback["sendFirebaseFeedback"]:::android
        end
        subgraph "iOSMain"
            IGPSService["CommonGPSLocationService"]:::ios
            iOSTTS["iOStextToSpeech"]:::ios
            iOSBilling["billingAction"]:::ios
            iONavigation["openNavigationAction"]:::ios
            iOFeedback["sendFirebaseFeeback"]:::ios
            iOWebAction["openWebUrlAction"]:::ios
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        HTTP["HTTP Endpoints"]:::external
        GoogleMaps["Google Maps SDK"]:::external
        BillingSDK["Billing SDKs (Play / StoreKit)"]:::external
        Firebase["Firebase Feedback"]:::external
    end

    %% Data Flow
    AndroidApp -->|"UI render"| SharedUI
    iOSApp -->|"UI render"| SharedUI
    SharedUI -->|"invoke use-case"| LoadMarkers
    SharedUI -->|"invoke use-case"| LoadMarkerDetails
    LoadMarkers -->|"calls"| HttpClient
    LoadMarkerDetails -->|"calls"| HttpClient
    HttpClient -->|"fetch HTML"| HTTP
    HttpClient -->|serialize| LatLongSerializer
    HttpClient -->|"parse"| ParseMarkersHtml
    HttpClient -->|"parse"| ParseDetailsHtml
    ParseMarkersHtml --> SharedUI
    ParseDetailsHtml --> SharedUI
    SharedUI -->|"billingAction"| BillingAction
    SharedUI -->|"navigate"| NavigationAction
    SharedUI -->|"openWeb"| WebAction
    SharedUI -->|"email"| EmailAction
    SharedUI -->|"feedback"| FeedbackAction
    BillingAction --> AndroidTTS
    BillingAction --> iOSBilling
    GPSService --> AGPSService
    GPSService --> IGPSService
    Speech --> AndroidTTS
    Speech --> iOSTTS
    NavigationAction --> ANavigation
    NavigationAction --> iONavigation
    WebAction --> iOWebAction
    FeedbackAction --> AFeedback
    FeedbackAction --> iOFeedback
    AGPSService -->|"location API"| GoogleMaps
    IGPSService -->|"location API"| GoogleMaps
    PurchaseManager -->|"billing API"| BillingSDK
    iOSBilling -->|"billing API"| BillingSDK

    %% Click Events
    click AndroidApp "https://github.com/realityexpander/fredsroadtripstoryteller/tree/main/androidApp/"
    click iOSApp "https://github.com/realityexpander/fredsroadtripstoryteller/tree/main/iosApp/"
    click SharedUI "https://github.com/realityexpander/fredsroadtripstoryteller/tree/main/shared/src/commonMain/kotlin/presentation"
    click MarkersRepo "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/data/MarkersRepo.kt"
    click AppSettings "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/data/AppSettings.kt"
    click LoadMarkers "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/data/loadMarkers/loadMarkers.kt"
    click LoadMarkerDetails "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/data/loadMarkerDetails/loadMarkerDetails.kt"
    click BillingAction "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/data/billing/CommonBilling.kt"
    click HttpClient "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/data/network/HttpClient.kt"
    click LatLongSerializer "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/data/network/LatLongSerializerSurrogate.kt"
    click ParseMarkersHtml "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/data/loadMarkers/parseMarkersPageHtml.kt"
    click ParseDetailsHtml "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/data/loadMarkerDetails/parseMarkerDetailsPageHtml.kt"
    click AppConfig "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/composeResources/files/appConfig.properties"
    click GPSService "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/CommonGPSLocationService.kt"
    click Speech "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/presentation/speech/CommonSpeech.kt"
    click NavigationAction "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/openNavigationAction.kt"
    click WebAction "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/openWebUrlAction.kt"
    click EmailAction "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/sendEmailAction.kt"
    click FeedbackAction "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/commonMain/kotlin/sendDeveloperFeedback.kt"
    click AGPSService "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/androidMain/kotlin/CommonGPSLocationService.kt"
    click AndroidTTS "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/androidMain/kotlin/AndroidTextToSpeech.kt"
    click PurchaseManager "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/androidMain/kotlin/ProductPurchaseAction.kt"
    click NotificationReceiver "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/androidMain/kotlin/gpsForegroundNotificationService/NotificationActionBroadcastReceiver.kt"
    click ANavigation "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/androidMain/kotlin/openNavigationAction.kt"
    click AFeedback "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/androidMain/kotlin/sendFirebaseFeedback.kt"
    click IGPSService "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/iosMain/kotlin/CommonGPSLocationService.kt"
    click iOSTTS "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/iosMain/kotlin/iOStextToSpeech.kt"
    click iOSBilling "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/iosMain/kotlin/billingAction.kt"
    click iONavigation "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/iosMain/kotlin/openNavigationAction.kt"
    click iOFeedback "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/iosMain/kotlin/sendFirebaseFeeback.kt"
    click iOWebAction "https://github.com/realityexpander/fredsroadtripstoryteller/blob/main/shared/src/iosMain/kotlin/openWebUrlAction.kt"

    %% Styles
    classDef shared fill:#D0E6FF,stroke:#004080,stroke-width:1px
    classDef android fill:#DFFFD0,stroke:#006400,stroke-width:1px
    classDef ios fill:#FFD0D0,stroke:#800000,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
