How bailuk/aat works
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).