# bailuk/aat architecture

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

- Interactive diagram: https://gitdiagram.com/bailuk/aat
- Repository: https://github.com/bailuk/aat

## Overview

##### Project Type and Purpose
- AAT (“Another Activity Tracker”) is a cross-platform, client-only GPS tracking application focused on cycling and related outdoor activities.
- It comprises three main Gradle modules:
- aat-lib: core, reusable platform-agnostic logic (GPX handling, map rendering abstractions, dispatcher, preferences, services interfaces)
- aat-android: Android-specific UI & services layer (Activities, Services, ContentProviders, Sensors, Android file I/O, Assets)
- aat-gtk: GTK desktop variant (Controllers, Views, GTK-specific implementations of services, H2 preferences DB, Flatpak packaging)

##### High-Level File Structure
- Top-level build files (settings.gradle.kts, build.gradle.kts) orchestrate a multi-module Gradle build.
- ci/: Continuous integration scripts & small CLI utilities.
- doc/: Manuals, compile instructions, UML templates.
- metadata/: App store metadata and screenshots.

##### Key Components
a. Core Library (aat-lib)
- Dispatcher subsystem (sources, filters, emitters)
- GPX parser/writer (XML parser layers, GPX data model)
- Abstractions (MapContext, TileProvider, Renderer, Layers)
- Services interfaces (LocationService, SensorService, CacheService, DirectoryService, RenderService)
- Preferences framework (Solid… classes)
- Utility modules (coordinates, html, xml, logger)

b. Android App (aat-android)
- UI layer: Activities (MainActivity, MapActivity, CockpitActivity…), custom Views & Layouts
- Service layer: Android Services (GpsLocation, SensorService, OneService), Broadcasts
- Data layer: ContentProviders (GpxDocumentProvider), local file system & SAF (Storage), SQLite DB (SensorListDb)
- Android-specific implementations of core interfaces (AndroidMapDirectories, AndroidSolidLocationProvider, AndroidDbConnection, AndroidTilePainter)

c. GTK App (aat-gtk)
- UI Controllers & Views (GtkAppContext, controllers for Clipboard, Overlay, Search, Preferences)
- GTK Views: Toplevel windows, dialogs, map canvas, graph canvas
- Service implementations: GeoClue2LocationProvider, H2DbConnection for preferences, RestClient for Overpass/Nominatim, GtkSyncTileBitmap & GtkTilePainter
- Flatpak packaging artifacts & gresource definitions

d. External Dependencies & Services
- Online Map Tiles (OpenStreetMap tile servers)
- Offline Maps (Mapsforge local map files)
- DEM3 Elevation Tiles (bailu.ch dem3 service)
- Overpass API (route overlays)
- Nominatim API (geocoding reverse lookups)
- Bluetooth LE sensors & internal sensors (heart rate, cycling power)
- F-Droid / GitHub Releases (distribution channels)

##### Relationships and Data Flows
- The Android and GTK apps each depend on and instantiate the core library’s abstractions.
- Both apps invoke LocationService → supplies location updates (GPS or mock).
- Dispatcher connects sources (GPS, Sensor, Track timer) → applies filters → emits to UI & storage.
- Rendering pipeline: MapContext → TileProvider → CacheService / online → TilePainter → UI canvas.
- GPX I/O: UI commands (record, edit) → GPX parser/writer → file storage / ContentProvider.
- Preferences: UI preference dialogs → Preferences framework ↔ Storage backend (Android SharedPreferences or H2 DB).
- External REST calls (Overpass/Nominatim) flow through utility classes (DownloadApi, OverpassApi, RestClient).
- Sensor data flows from Bluetooth LE stack or internal sensors into SensorService → Dispatcher → UI.

##### Architectural Patterns & Principles
- Modular multi-project build separating core logic from platform specifics.
- Clean separation of concerns: UI / Service / Data layers.
- Interface-based programming: core defines service interfaces, platforms supply implementations.
- Dispatcher (event bus) for decoupled communication between subsystems.
- Factory patterns for map and view creation (MapFactory, GraphViewFactory).
- MVC/MVP-like structure in GTK (Controller ↔ View) and Android (Activity ↔ custom Views/Adapters).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Module
    subgraph "aat-lib" 
        direction TB
        DL["Dispatcher"]:::core
        GPX["GPX Parser/Writer"]:::core
        MAPCTX["MapContext"]:::core
        TILEPROV["TileProvider"]:::core
        TILEPAINT["TilePainter"]:::core
        SVCINT["Services Interfaces"]:::core
        PREF["Preferences Framework"]:::core
        UTIL["Utilities"]:::core
    end

    %% Android App Module
    subgraph "aat-android" 
        direction TB
        subgraph "UI Layer"
            direction TB
            MainAct["MainActivity"]:::ui
            MapAct["MapActivity"]:::ui
            CockAct["CockpitActivity"]:::ui
        end
        subgraph "Service Layer"
            direction TB
            GpsLoc["GpsLocation Service"]:::service
            SensorSvc["SensorService"]:::service
            OneSvc["OneService"]:::service
        end
        subgraph "Data Layer"
            direction TB
            GpxProv["GpxDocumentProvider"]:::service
            SensorDB["SensorListDb"]:::service
            DbConn["AndroidDbConnection"]:::service
        end
        subgraph "Assets"
            direction TB
            Icons["icons"]:::service
            MapFeat["map-features"]:::service
        end
        subgraph "Core Implementations"
            direction TB
            AndTilePaint["AndroidTilePainter"]:::service
            AndMapDir["AndroidMapDirectories"]:::service
            AndLocProv["AndroidSolidLocationProvider"]:::service
        end
    end

    %% GTK App Module
    subgraph "aat-gtk"
        direction TB
        subgraph "UI Controllers & Views"
            direction TB
            ClipCtrl["ClipboardController"]:::ui
            OverCtrl["OverlayController"]:::ui
            MainWin["MainWindow"]:::ui
            GtkMapCtx["GtkMapContext"]:::ui
        end
        GtkBroad["GtkBroadcaster"]:::service
        subgraph "Service Implementations"
            direction TB
            GeoClue["GeoClue2LocationProvider"]:::service
            H2Conn["H2DbConnection"]:::service
            RestCli["RestClient"]:::service
            GtkTile["GtkTilePainter"]:::service
        end
        subgraph "Packaging"
            direction TB
            Flatpak["Flatpak JSON"]:::service
            Gres["Gresource XML"]:::service
        end
    end

    %% External Dependencies
    subgraph "External" 
        direction TB
        OSM["OpenStreetMap Tiles"]:::external
        OffMap["Offline Maps (Mapsforge)"]:::external
        DEM3["DEM3 Elevation Tiles"]:::external
        Overpass["Overpass API"]:::external
        Nominatim["Nominatim API"]:::external
        BLE["Bluetooth LE Sensors"]:::external
        GitHub["F-Droid/GitHub Releases"]:::external
    end

    %% Dependencies
    aat-android -->|depends on| aat-lib
    aat-gtk -->|depends on| aat-lib

    %% Core flows
    GPX -->|used by| GpxProv
    MAPCTX --> TILEPROV -->|requests tiles| CacheService["CacheServiceInterface"]:::core
    TILEPROV -->|online| OSM
    TILEPROV -->|offline| OffMap
    TILEPROV -->|elevation| DEM3
    TILEPAINT -->|renders to| MapAct
    DL -->|dispatches| MainAct
    DL -->|dispatches| GtkMapCtx

    %% Android flows
    GpsLoc -->|publishes location| DL
    SensorSvc -->|publishes sensor data| DL
    MainAct -->|commands| GpxProv
    GpxProv -->|reads/writes| FileSys["File System"]:::service
    MapAct -->|renders| TILEPAINT
    CockAct -->|shows stats| UTIL

    %% GTK flows
    GeoClue -->|location| DL
    RestCli -->|calls| Overpass
    RestCli -->|calls| Nominatim
    GtkMapCtx -->|renders map| GtkTile
    ClipCtrl -->|copy/paste| UTIL

    %% External flows
    BLE -->|data| SensorSvc
    GitHub -->|distribution| MainAct

    %% Click Events Core
    click DL "https://github.com/bailuk/aat/tree/master/aat-lib/src/main/java/ch/bailu/aat_lib/dispatcher"
    click GPX "https://github.com/bailuk/aat/tree/master/aat-lib/src/main/java/ch/bailu/aat_lib/gpx"
    click MAPCTX "https://github.com/bailuk/aat/blob/master/aat-lib/src/main/java/ch/bailu/aat_lib/map/MapContext.kt"
    click TILEPROV "https://github.com/bailuk/aat/blob/master/aat-lib/src/main/java/ch/bailu/aat_lib/map/tile/TileProvider.kt"
    click TILEPAINT "https://github.com/bailuk/aat/blob/master/aat-lib/src/main/java/ch/bailu/aat_lib/map/TilePainter.kt"
    click SVCINT "https://github.com/bailuk/aat/blob/master/aat-lib/src/main/java/ch/bailu/aat_lib/service/location/LocationServiceInterface.kt"
    click PREF "https://github.com/bailuk/aat/tree/master/aat-lib/src/main/java/ch/bailu/aat_lib/preferences"
    click UTIL "https://github.com/bailuk/aat/tree/master/aat-lib/src/main/java/ch/bailu/aat_lib/util"

    %% Click Events Android
    click MainAct "https://github.com/bailuk/aat/blob/master/aat-android/src/main/kotlin/ch/bailu/aat/activities/MainActivity.kt"
    click MapAct "https://github.com/bailuk/aat/blob/master/aat-android/src/main/kotlin/ch/bailu/aat/activities/MapActivity.kt"
    click CockAct "https://github.com/bailuk/aat/blob/master/aat-android/src/main/kotlin/ch/bailu/aat/activities/CockpitActivity.kt"
    click GpsLoc "https://github.com/bailuk/aat/blob/master/aat-android/src/main/kotlin/ch/bailu/aat/services/location/GpsLocation.kt"
    click SensorSvc "https://github.com/bailuk/aat/blob/master/aat-android/src/main/kotlin/ch/bailu/aat/services/sensor/SensorService.kt"
    click OneSvc "https://github.com/bailuk/aat/blob/master/aat-android/src/main/kotlin/ch/bailu/aat/services/OneService.kt"
    click GpxProv "https://github.com/bailuk/aat/blob/master/aat-android/src/main/kotlin/ch/bailu/aat/providers/GpxDocumentProvider.kt"
    click SensorDB "https://github.com/bailuk/aat/blob/master/aat-android/src/main/kotlin/ch/bailu/aat/services/sensor/list/SensorListDb.kt"
    click DbConn "https://github.com/bailuk/aat/blob/master/aat-android/src/main/kotlin/ch/bailu/aat/util/sql/AndroidDbConnection.kt"
    click Icons "https://github.com/bailuk/aat/tree/master/aat-android/src/main/assets/icons"
    click MapFeat "https://github.com/bailuk/aat/tree/master/aat-android/src/main/assets/map-features"
    click AndTilePaint "https://github.com/bailuk/aat/blob/master/aat-android/src/main/kotlin/ch/bailu/aat/map/AndroidTilePainter.kt"
    click AndMapDir "https://github.com/bailuk/aat/blob/master/aat-android/src/main/kotlin/ch/bailu/aat/preferences/map/AndroidMapDirectories.kt"
    click AndLocProv "https://github.com/bailuk/aat/blob/master/aat-android/src/main/kotlin/ch/bailu/aat/preferences/location/AndroidSolidLocationProvider.kt"

    %% Click Events GTK
    click ClipCtrl "https://github.com/bailuk/aat/blob/master/aat-gtk/src/main/kotlin/ch/bailu/aat_gtk/controller/ClipboardController.kt"
    click OverCtrl "https://github.com/bailuk/aat/blob/master/aat-gtk/src/main/kotlin/ch/bailu/aat_gtk/controller/OverlayController.kt"
    click MainWin "https://github.com/bailuk/aat/blob/master/aat-gtk/src/main/kotlin/ch/bailu/aat_gtk/view/toplevel/MainWindow.kt"
    click GtkMapCtx "https://github.com/bailuk/aat/blob/master/aat-gtk/src/main/kotlin/ch/bailu/aat_gtk/view/map/GtkMapContext.kt"
    click GtkBroad "https://github.com/bailuk/aat/blob/master/aat-gtk/src/main/kotlin/ch/bailu/aat_gtk/dispatcher/GtkBroadcaster.kt"
    click GeoClue "https://github.com/bailuk/aat/blob/master/aat-gtk/src/main/kotlin/ch/bailu/aat_gtk/service/location/GeoClue2LocationProvider.kt"
    click H2Conn "https://github.com/bailuk/aat/blob/master/aat-gtk/src/main/kotlin/ch/bailu/aat_gtk/util/sql/H2DbConnection.kt"
    click RestCli "https://github.com/bailuk/aat/blob/master/aat-gtk/src/main/kotlin/ch/bailu/aat_gtk/lib/rest/RestClient.kt"
    click GtkTile "https://github.com/bailuk/aat/blob/master/aat-gtk/src/main/kotlin/ch/bailu/aat_gtk/map/GtkTilePainter.kt"
    click Flatpak "https://github.com/bailuk/aat/blob/master/aat-gtk/flatpak/ch.bailu.aat.json"
    click Gres "https://github.com/bailuk/aat/blob/master/aat-gtk/gresource/app.xml"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef service fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef core fill:#e2e3e5,stroke:#333,stroke-width:1px
```
