# dear-luca/echo architecture

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

- Interactive diagram: https://gitdiagram.com/dear-luca/echo
- Repository: https://github.com/dear-luca/echo

## Overview

##### Project Type & Purpose
- Echo is a *Kotlin Multiplatform* mobile app (Android + iOS) for *decentralized, GPS-based messaging* using aggregate computing (Collektive) and MQTT transport.
- It consists of:
- A shared Kotlin “commonMain” layer (business logic, gossip algorithms, models, serializers, network abstractions).
- Two platform UIs: Compose for Android, SwiftUI for iOS.
- Platform adapters for location & MQTT mailbox.
- CI/CD (Fastlane + GitHub Actions).

##### Top-Level Components
1. UI Layer
– Android: Compose Multiplatform (MainActivity.kt, Compose screens, viewmodels)
– iOS: SwiftUI (MainViewController.swift, ContentView.swift)
2. Business Logic Layer (commonMain)
– App.kt (entrypoint), ViewModels (NearbyDevicesViewModel), Models (ChatMessage, DeviceLocationHeartbeat)
– GossipAlgorithms (location-aware gradient gossip) via Collektive
– Serialization & Networking (AbstractSerializerMailbox, MqttMailbox)
3. Platform Adapters
– LocationServiceFactory & PlatformLocationService (android/ios implementations)
– LocationPermissionHandler (android/ios)
– MQTT mailbox binds to platform’s network stack (WebSockets over mobile network)
4. External Services
– GPS hardware & OS location APIs
– Public MQTT broker (message routing)

##### Relationships & Data Flow
- UI Layer ←→ Business Logic
- UI triggers ViewModel actions (e.g., “send message”, “request neighbors”)
- ViewModel exposes LiveState for UI to render (nearby devices, incoming messages)
- Business Logic → Gossip Algorithm Engine (Collektive)
- Applies aggregate computing rounds on neighbor data
- Business Logic → Platform Adapters
- Requests location updates from LocationService
- Publishes and subscribes to messages via MqttMailbox
- Platform Adapters → External Services
- LocationService queries GPS APIs
- MqttMailbox connects to public broker (over WebSockets/TCP)

##### Architectural Patterns & Principles
- **Modular layering**: UI / BL / Adapters / External
- **Aggregate computing**: Single global program compiles to local gossip execution
- **Decentralized gossip**: Peer-to-peer, no central coordinator
- **Kotlin Multiplatform**: Shared business logic, platform-specific UI & services
- **MQTT transport**: QoS and WebSocket support for mobile

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        MainActivity["MainActivity.kt"]:::blue
        PlatformAndroid["Platform.android.kt"]:::blue
        Screen["Screen.kt"]:::blue
        TopBar["TopBar.kt"]:::blue
        ContentView["ContentView.swift"]:::blue
        iOSApp["iOSApp.swift"]:::blue
        MainViewController["MainViewController.kt"]:::blue
        PlatformiOS["Platform.ios.kt"]:::blue
    end

    %% Business Logic Layer
    subgraph "Business Logic" 
        direction TB
        App["App.kt"]:::green
        Constant["Constant.kt"]:::green
        Greeting["Greeting.kt"]:::green
        ViewModel["NearbyDevicesViewModel.kt"]:::green
        ChatMessage["ChatMessage.kt"]:::green
        DeviceHeartbeat["DeviceLocationHeartbeat.kt"]:::green
        GossipAlgo["GossipAlgorithms.kt"]:::green
        MessageModel["Message.kt"]:::green
        UuidSerializer["UuidSerializer.kt"]:::green
        AbstractMailbox["AbstractSerializerMailbox.kt"]:::green
        MqttMailbox["MqttMailbox.kt"]:::green
    end

    %% Platform Adapters
    subgraph "Platform Adapters"
        direction TB
        LocationServiceFactory["LocationServiceFactory.kt"]:::orange
        PlatformLocationService["PlatformLocationService.kt"]:::orange
        PermissionHandler["LocationPermissionHandler.kt"]:::orange
        LocationServiceFactoryAndroid["LocationServiceFactory.android.kt"]:::orange
        PlatformLocationServiceAndroid["PlatformLocationService.android.kt"]:::orange
        PermissionHandlerAndroid["LocationPermissionHandler.android.kt"]:::orange
        LocationServiceFactoryiOS["LocationServiceFactory.ios.kt"]:::orange
        PlatformLocationServiceiOS["PlatformLocationService.ios.kt"]:::orange
        PermissionHandleriOS["LocationPermissionHandler.ios.kt"]:::orange
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GPS["GPS / OS API"]:::gray
        MQTTBroker["MQTT Broker"]:::gray
    end

    %% Data Flow
    MainActivity -->|triggers| App
    PlatformAndroid -->|triggers| App
    Screen -->|binds to| ViewModel
    TopBar -->|binds to| ViewModel
    ContentView -->|triggers| App
    iOSApp -->|triggers| App
    MainViewController -->|triggers| App
    PlatformiOS -->|triggers| App

    App -->|uses| GossipAlgo
    App -->|uses| ViewModel
    GossipAlgo -->|uses| DeviceHeartbeat
    GossipAlgo -->|uses| ChatMessage
    App -->|serializes| UuidSerializer
    App -->|sends/receives| AbstractMailbox
    AbstractMailbox -->|implemented by| MqttMailbox

    App -->|requests location| LocationServiceFactory
    App -->|requests permission| PermissionHandler
    LocationServiceFactory -->|android impl| LocationServiceFactoryAndroid
    LocationServiceFactory -->|ios impl| LocationServiceFactoryiOS
    PlatformLocationService -->|android impl| PlatformLocationServiceAndroid
    PlatformLocationService -->|ios impl| PlatformLocationServiceiOS
    PermissionHandler -->|android impl| PermissionHandlerAndroid
    PermissionHandler -->|ios impl| PermissionHandleriOS

    LocationServiceFactory -->|queries| GPS
    MqttMailbox -->|connects to| MQTTBroker

    GPS -->|updates| PlatformLocationService
    PlatformLocationService -->|callback| App
    MQTTBroker -->|pushes messages| MqttMailbox
    MqttMailbox -->|delivers| App
    App -->|updates| ViewModel
    ViewModel -->|renders| Screen
    ViewModel -->|renders| TopBar
    ViewModel -->|renders| ContentView

    %% Click Events
    click MainActivity "https://github.com/dear-luca/echo/blob/main/composeApp/src/androidMain/kotlin/com/example/echo/MainActivity.kt"
    click PlatformAndroid "https://github.com/dear-luca/echo/blob/main/composeApp/src/androidMain/kotlin/com/example/echo/Platform.android.kt"
    click Screen "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/ui/Screen.kt"
    click TopBar "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/ui/TopBar.kt"
    click ContentView "https://github.com/dear-luca/echo/blob/main/iosApp/iosApp/ContentView.swift"
    click iOSApp "https://github.com/dear-luca/echo/blob/main/iosApp/iosApp/iOSApp.swift"
    click MainViewController "https://github.com/dear-luca/echo/blob/main/composeApp/src/iosMain/kotlin/MainViewController.kt"
    click PlatformiOS "https://github.com/dear-luca/echo/blob/main/composeApp/src/iosMain/kotlin/com/example/echo/Platform.ios.kt"
    click App "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/App.kt"
    click Constant "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/Constant.kt"
    click Greeting "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/Greeting.kt"
    click ViewModel "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/viewmodels/NearbyDevicesViewModel.kt"
    click ChatMessage "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/models/ChatMessage.kt"
    click DeviceHeartbeat "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/models/DeviceLocationHeartbeat.kt"
    click GossipAlgo "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/gossip/GossipAlgorithms.kt"
    click MessageModel "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/gossip/Message.kt"
    click UuidSerializer "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/serialization/UuidSerializer.kt"
    click AbstractMailbox "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/network/AbstractSerializerMailbox.kt"
    click MqttMailbox "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/network/mqtt/MqttMailbox.kt"
    click LocationServiceFactory "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/location/LocationServiceFactory.kt"
    click PlatformLocationService "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/location/PlatformLocationService.kt"
    click PermissionHandler "https://github.com/dear-luca/echo/blob/main/composeApp/src/commonMain/kotlin/com/example/echo/location/LocationPermissionHandler.kt"
    click LocationServiceFactoryAndroid "https://github.com/dear-luca/echo/blob/main/composeApp/src/androidMain/kotlin/com/example/echo/location/LocationServiceFactory.android.kt"
    click PlatformLocationServiceAndroid "https://github.com/dear-luca/echo/blob/main/composeApp/src/androidMain/kotlin/com/example/echo/location/PlatformLocationService.android.kt"
    click PermissionHandlerAndroid "https://github.com/dear-luca/echo/blob/main/composeApp/src/androidMain/kotlin/com/example/echo/location/LocationPermissionHandler.android.kt"
    click LocationServiceFactoryiOS "https://github.com/dear-luca/echo/blob/main/composeApp/src/iosMain/kotlin/com/example/echo/location/LocationServiceFactory.ios.kt"
    click PlatformLocationServiceiOS "https://github.com/dear-luca/echo/blob/main/composeApp/src/iosMain/kotlin/com/example/echo/location/PlatformLocationService.ios.kt"
    click PermissionHandleriOS "https://github.com/dear-luca/echo/blob/main/composeApp/src/iosMain/kotlin/com/example/echo/location/LocationPermissionHandler.ios.kt"

    %% Styles
    classDef blue fill:#cce5ff,stroke:#004085,color:#004085;
    classDef green fill:#d4edda,stroke:#155724,color:#155724;
    classDef orange fill:#ffe5b4,stroke:#ff8c00,color:#ff8c00;
    classDef gray fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
