Camí de Cavalls

A modern Kotlin Multiplatform trekking/hiking application for exploring the legendary Camí de Cavalls trail in Menorca, Spain. This 185km coastal path is divided into 20 distinct stages, offering hikers an unforgettable journey around the island.

📱 Project Overview

Camí de Cavalls is a production-ready mobile application designed for both Android and iOS platforms, showcasing best practices in Kotlin Multiplatform development. The app serves as both a portfolio project and a commercial application targeting local partnerships with Menorcan businesses.

Key Features

Implemented:

📍 GPS Tracking: Real-time location tracking with high accuracy (5s intervals, 5m minimum distance)
📡 Background Tracking: Reliable GPS tracking that continues when the app is in the background
- Android: Foreground service with persistent notification, wake lock, and START_STICKY restart recovery
- iOS: CoreLocation background mode with blue status bar indicator
- Process death recovery: tracking state persisted to SharedPreferences, automatic session restore on app reopen
⏱️ Live Duration: Real-time duration counter during tracking, independent from GPS updates
📴 Offline Mode: Complete offline support - all data stored locally in SQLDelight, GPS works without internet
📝 Notebook: Track hiking sessions with automatic statistics calculation (distance via Haversine formula, duration, elevation, speed)
📄 Session Details: View recorded sessions with gradient-colored track visualization (green→yellow→red based on altitude)
📤 GPX Export: Share recorded sessions as GPX files via system share sheet (Android & iOS)
🔐 Location Permissions: Smart permission handling with native dialogs for Android and iOS
🗺️ Route Database: Complete data for all 20 Camí de Cavalls stages with accurate KML data (~185km, ~2,480m elevation gain, ~55 hours)
📊 Session Statistics: Automatic calculation of distance, speed, elevation gain/loss during tracking
🗺️ Interactive Maps: MapLibre integration with route visualization, markers, and smooth map interaction on both platforms
🎯 Accurate Route Data: All 20 routes converted from official KML source with ~130 optimized points per route
🧭 GPS Toggle Button: Smart GPS following with automatic disable on map gestures (pan, zoom) - works consistently on both Android and iOS
🌍 Multilingual: Full support for 6 languages (Catalan, Spanish, English, French, German, Italian) with custom localization system, multilingual route descriptions, and localized settings screen
📊 Elevation Charts: Interactive elevation profiles with tap/drag gestures, centered tooltips, map synchronization, and smooth curve rendering
⚙️ Settings Hub: Dedicated settings screen with language selection, about page, and contact options
🏛️ Points of Interest: Complete database of 190 POIs with multilingual content (6 languages) - coastal zones, natural areas, and historic sites with accurate coordinates from official map
🧭 Bottom Navigation Bar: WeWard-style dark bottom bar with 5 tabs (Map, Routes, POI, Diary, Settings) replacing the drawer menu
🗺️ Complete Route: Virtual "Complete Route" (185km full loop Maó–Maó) combining all 20 stages with aggregated statistics, elevation profile, and combined GeoJSON track
📊 Session Summary Overlay: Post-tracking session summary displayed as a dark card overlay on the map with key statistics
📱 Android Immersive Mode: Full-screen experience hiding system navigation bar with swipe-to-reveal
🔔 POI Proximity Notifications: Real-time local notifications when approaching nearby POIs during tracking, with tap-to-open POI detail popup (both Android and iOS), notification view analytics tracked to backend with offline queue
🎬 Animated Splash Screen: Menorca silhouette with route tracing animation, cross-fade to logo, randomized horse/horseshoe variant
🌦️ Weather Forecast: 5-day weather forecast popup via Open-Meteo API with daily temperature, precipitation, and weather icons
🔑 User Authentication: Email/password registration with email verification, Google OAuth (Android & iOS), Apple Sign-In (iOS only), user profile with avatar upload
⭐ Likes & Reviews: Route and POI like system (device-based + authenticated), user reviews with star ratings and localized timestamps
⚠️ Danger Reports: Submit trail hazard reports with photos (up to 4), GPS coordinates, and description; offline queue with automatic retry and sync; blocked user prevention on photo uploads
🎨 Polished UI: Complete Material 3 color scheme (sea-blue palette), consistent dark FAB buttons during tracking, rich card layouts with route images and gradient overlays for Notebook and Danger Reports lists, image carousel with swipe and dot indicators

Business Model

V1: Free app with essential features, user accounts, likes, reviews, and danger reports
V2: Integration with local businesses (restaurants, hotels, shops) for commercial partnerships

Data Strategy

The application is designed to be independent from external sources:

Route data, GPX files, and POI information are stored locally in the app
Optional backend integration for dynamic content updates
No dependencies on third-party websites for core functionality
Data sourced from official Camí de Cavalls resources (camidecavalls.com) but stored and managed independently

🏗️ Architecture

The project follows Clean Architecture principles with clear separation of concerns:

composeApp/
├── src/
│   ├── commonMain/
│   │   ├── kotlin/
│   │   │   ├── domain/           # Business logic layer
│   │   │   │   ├── model/        # Domain entities
│   │   │   │   │   ├── Route.kt
│   │   │   │   │   ├── PointOfInterest.kt
│   │   │   │   │   ├── TrackingSession.kt
│   │   │   │   │   └── TrackPoint.kt
│   │   │   │   └── repository/   # Repository interfaces
│   │   │   ├── data/             # Data layer
│   │   │   │   ├── local/        # Database (SQLDelight)
│   │   │   │   └── repository/   # Repository implementations
│   │   │   ├── di/               # Dependency injection (Koin)
│   │   │   └── presentation/     # UI layer
│   │   └── sqldelight/           # Database schema
│   │       └── com/followmemobile/camidecavalls/database/
│   │           ├── Route.sq
│   │           ├── PointOfInterest.sq
│   │           ├── TrackingSession.sq
│   │           └── TrackPoint.sq
│   ├── androidMain/              # Android-specific code
│   │   └── kotlin/
│   │       ├── data/local/       # Android SQLite driver
│   │       └── di/               # Android DI module
│   └── iosMain/                  # iOS-specific code
│       └── kotlin/
│           ├── data/local/       # iOS SQLite driver
│           └── di/               # iOS DI module
└── iosApp/                       # iOS application wrapper

Layers

Domain Layer (Pure Kotlin)
- Business entities and models (Route, POI, TrackingSession, TrackPoint)
- Repository interfaces
- Use cases (18 implemented):
  - Route management: GetAllRoutes, GetRouteById, GetRouteByNumber, SaveRoutes, InitializeDatabase
  - POI management: GetAllPOIs, GetPOIsByType, GetPOIsNearLocation, GetPOIsByRoute, SavePOIs
  - Tracking: StartSession, StopSession, AddTrackPoint, CalculateStats, GetActiveSession, GetAllSessions, GetSessionById, DeleteSession
- Services: LocationService, PermissionHandler
Data Layer
- Repository implementations with Flow-based reactive queries
- Local database (SQLDelight) with 4 tables and optimized indexes
- LocationService implementations (Android: FusedLocationProvider, iOS: CoreLocation)
- PermissionHandler implementations (platform-specific dialogs)
- Platform-specific implementations (expect/actual)
Presentation Layer
- MainScreen with bottom navigation bar (5 tabs: Map, Routes, POI, Notebook, Settings)
- ScreenModels (Voyager): RoutesScreenModel, RouteDetailScreenModel, TrackingScreenModel, NotebookScreenModel, POIsScreenModel, SettingsScreenModel, AboutScreenModel
- Tab content: MapTabContent (GPS + routes), RoutesTabContent (route list + complete route), POIsTabContent (POI map + filters), NotebookTabContent (session diary), SettingsHubContent (settings hub)
- Detail screens: RouteDetailScreen, SessionDetailScreen, POIDetailScreen, LanguageSettingsScreen, AboutCamiScreen
- Auth screens: LoginScreen, AccountScreen with Google OAuth integration
- Interactive components: ElevationChart with Canvas API, WeWardBottomBar, CompletedOverlay, ImageCarousel (HorizontalPager)
- Sheets: DangerReportSheet, ReviewSheet, ReviewsListSheet
- Settings: DangerReportsQueueScreen, DevDebugScreen
- RouteSelectionManager for cross-tab route communication
- Navigation with Voyager (detail screens pushed on top of MainScreen)
- Material 3 UI with complete sea-blue color scheme

🛠️ Tech Stack

Core

Kotlin 2.2.0: Programming language
Kotlin Multiplatform: Code sharing across platforms
Compose Multiplatform 1.9.1: Declarative UI framework

Architecture & Patterns

Clean Architecture: Separation of concerns
MVVM Pattern: Model-View-ViewModel
Repository Pattern: Data access abstraction
Expect/Actual: Platform-specific implementations

Libraries

Dependency Injection

Koin 4.0.0: Lightweight DI framework

Database

SQLDelight 2.0.2: Type-safe SQL database
- 4 tables: Routes, POIs, Tracking Sessions, Track Points
- Optimized indexes for location queries
- Foreign keys with cascade deletes

Networking

Ktor 3.0.1: HTTP client (backend API, Open-Meteo weather API)

Image Loading

Coil 3: Multiplatform image loading (SubcomposeAsyncImage for route photos, avatars, danger report images)

Navigation

Voyager 1.1.0-beta02: Type-safe navigation

Async & Reactive

Kotlinx Coroutines 1.9.0: Asynchronous programming
Kotlinx Flow: Reactive streams

Serialization

Kotlinx Serialization 1.7.3: JSON serialization
Kotlinx DateTime 0.6.1: Date/time handling

Logging

Napier 2.7.1: Multiplatform logging

Maps

MapLibre Compose 0.0.7: Interactive maps with native rendering
- Android: MapLibre Native Android with AndroidView integration
- iOS: MapLibre Native iOS with UIKitView integration
- OpenFreeMap tiles for offline-capable map rendering
- Route path rendering with LineLayer
- Marker support with CircleLayer
- Platform-specific MapLayerController with expect/actual pattern

Location

Google Play Services Location 21.3.0: GPS tracking (Android)
Core Location: GPS tracking (iOS)

Settings

Multiplatform Settings 1.2.0: Key-value storage

📊 Database Schema

RouteEntity

Stores the 20 stages of Camí de Cavalls.

- id: INTEGER PRIMARY KEY
- number: INTEGER UNIQUE (1-20)
- name: TEXT
- startPoint: TEXT
- endPoint: TEXT
- distanceKm: REAL
- elevationGainMeters: INTEGER
- elevationLossMeters: INTEGER
- maxAltitudeMeters: INTEGER
- minAltitudeMeters: INTEGER
- asphaltPercentage: INTEGER
- difficulty: TEXT (LOW, MEDIUM, HIGH)
- estimatedDurationMinutes: INTEGER
- description: TEXT
- gpxData: TEXT (nullable)
- imageUrl: TEXT (nullable)

PointOfInterestEntity

Stores natural, historic, and commercial POIs.

- id: INTEGER PRIMARY KEY
- name: TEXT
- type: TEXT (NATURAL, HISTORIC, BEACH, VIEWPOINT, etc.)
- latitude: REAL
- longitude: REAL
- description: TEXT
- images: TEXT (JSON array)
- routeId: INTEGER (nullable, FK to Route)
- isAdvertisement: INTEGER (0/1)

Indexes:

poi_location_idx on (latitude, longitude)
poi_type_idx on (type)

TrackingSessionEntity

Stores user hiking sessions (Notebook feature).

- id: TEXT PRIMARY KEY
- routeId: INTEGER (nullable, FK to Route)
- startTime: INTEGER (epoch milliseconds)
- endTime: INTEGER (nullable)
- distanceMeters: REAL
- durationSeconds: INTEGER
- averageSpeedKmh: REAL
- maxSpeedKmh: REAL
- elevationGainMeters: INTEGER
- elevationLossMeters: INTEGER
- isCompleted: INTEGER (0/1)
- notes: TEXT

TrackPointEntity

Stores GPS points for each tracking session.

- id: INTEGER PRIMARY KEY AUTOINCREMENT
- sessionId: TEXT (FK to TrackingSession, CASCADE DELETE)
- latitude: REAL
- longitude: REAL
- altitude: REAL (nullable)
- timestamp: INTEGER (epoch milliseconds)
- speedKmh: REAL (nullable)

Indexes:

track_point_session_idx on (sessionId)
track_point_timestamp_idx on (timestamp)

RemotePoiEntity

Stores POIs synced from the backend.

PendingViewEntity

Offline queue for view analytics (deduplication via composite primary key).

- targetType: TEXT (POI, DANGER_REPORT)
- targetId: TEXT
- viewType: TEXT (PREVIEW, DETAIL, NOTIFICATION)
- createdAt: TEXT
- PRIMARY KEY (targetType, targetId, viewType)

🚀 Getting Started

Requirements

Android Studio Ladybug (2024.2.1) or later
Xcode 15.0 or later (for iOS development)
JDK 11 or later
Gradle 8.10.2 (included via wrapper)

Setup

Clone the repository

git clone <repository-url>
cd CamíDeCavalls

Open in Android Studio
- File → Open → Select project directory
- Wait for Gradle sync to complete
For iOS development (macOS only)
- Ensure Xcode is installed
- Open iosApp/iosApp.xcodeproj in Xcode
- Important: Add libsqlite3.tbd to "Link Binary With Libraries" in Build Phases
- Build the project

Running the Application

Android (Build Variants)

The app uses product flavors (dev / production) × build types (debug / release):

Variant	API URL	App ID
`devDebug`	`http://192.168.8.106:3002`	`com.followmemobile.camidecavalls.dev`
`productionDebug`	`https://camidecavalls.followtheflowai.com`	`com.followmemobile.camidecavalls`
`productionRelease`	`https://camidecavalls.followtheflowai.com`	`com.followmemobile.camidecavalls`

Open project in Android Studio
Select the desired build variant in Build → Select Build Variant
Click Run (or press ⌃R)

To change the dev API URL (e.g., your LAN IP), edit the dev flavor in composeApp/build.gradle.kts:

buildConfigField("String", "API_BASE_URL", "\"http://YOUR_IP:3002\"")

iOS (Xcode Schemes)

Two shared schemes with separate bundle IDs (installed as separate apps):

Scheme	Configuration	API URL	Bundle ID
iosApp Dev	Debug	`http://192.168.8.106:3002`	`com.followmemobile.camidecavalls.dev`
iosApp Production	ProductionDebug	`https://camidecavalls.followtheflowai.com`	`com.followmemobile.camidecavalls`

Open iosApp/iosApp.xcodeproj in Xcode
Select the desired scheme (iosApp Dev or iosApp Production)
Click Run (or press ⌘R)

iOS Configurations:

Debug: Fast compilation, dev settings (used by iosApp Dev scheme)
ProductionDebug: Fast compilation, production settings (used by iosApp Production scheme)
Release: Optimized compilation for App Store distribution

DEV Environment Indicators

Dev builds include visual indicators on both platforms:

App Icon: Red banner with white "DEV" text at the bottom of the icon
In-App Ribbon: Diagonal red ribbon with "DEV" text in the top-left corner (only visible when AppConfig.isDebug is true)

Building for Production

Android

./gradlew :composeApp:assembleProductionRelease

APK location: composeApp/build/outputs/apk/production/release/

iOS

Build in Xcode with the Release configuration for App Store distribution.

🗓️ Development Roadmap

✅ Milestone 1: Foundation & Architecture (COMPLETED)

Project setup and configuration
Clean Architecture structure
Domain models (Route, POI, TrackingSession, TrackPoint)
SQLDelight database implementation with 4 tables
Repository pattern implementation with Flow
Dependency injection with Koin 4.0.0
Android build working
iOS build working

✅ Milestone 2: Business Logic & Data (COMPLETED)

Use Cases implementation (18 total)
- Route management: GetAll, GetById, GetByNumber, Save, InitializeDatabase
- POI queries: GetAll, ByType, NearLocation, ByRoute, Save
- Tracking: Start, Stop, AddPoint, CalculateStats, GetActive, GetAll, GetById, Delete
Route data preparation
- All 20 Camí de Cavalls stages with realistic data
- Database initialization on first app launch
- Offline-first data strategy
TrackingManager with battery optimization

✅ Milestone 3: Core UI & Navigation (COMPLETED)

Navigation setup with Voyager
HomeScreen with route list (Material 3 cards)
RouteDetailScreen with complete route information
TrackingScreen (Notebook) with real-time GPS
Location permission handling (Android & iOS)

✅ Milestone 4: GPS Tracking & Permissions (COMPLETED)

✅ Milestone 5: Interactive Maps & Route Visualization (COMPLETED)

✅ Milestone 6: Elevation Charts & Settings (COMPLETED)

✅ Milestone 7: POI System (COMPLETED)

POI data collection (190 POIs from official website)
Multilingual scraping (6 languages: CA, ES, EN, DE, FR, IT)
Coordinate correction (UTM to WGS84 conversion)
POI database with versioning system
POI categories: Coastal zones, Natural areas, Historic sites

✅ Milestone 8: Bottom Navigation & UI Restructuring (COMPLETED)

✅ Milestone 9: Notifications, Splash & Weather (COMPLETED)

✅ Milestone 10: Backend CRM & Remote POI Sync (COMPLETED)

✅ Milestone 11: User Engagement & Authentication (COMPLETED)

🌐 Future: Advanced Features

📝 Current Status

Milestones 1-11 Completed ✅

The app is now fully functional with core trekking features, interactive maps, elevation charts, settings, complete POI database, bottom navigation bar, user authentication, social features (likes, reviews), and danger reporting:

Architecture & Foundation:

Clean Architecture fully implemented across 3 layers
SQLDelight database with 4 tables and optimized indexes
Repository pattern with Flow-based reactive queries
Koin 4.0.0 dependency injection (platform-specific modules)
Cross-platform compilation verified (Android + iOS)
AppPreferences system for database versioning

Business Logic:

18 use cases implemented and tested
Accurate route data for all 20 Camí de Cavalls stages (~185km)
All routes converted from official KML source
TrackingManager with battery-optimized GPS tracking
Haversine formula for accurate distance calculation
Automatic statistics calculation (distance, speed, elevation)

User Interface:

Material 3 design system
Voyager navigation (type-safe, without voyager-koin)
Bottom navigation bar with 5 tabs (Map, Routes, POI, Diary, Settings)
- WeWard-style dark theme with blue accent for selected tab
- Variable weight layout for proportional label sizing
- Auto-hides during active GPS tracking for maximum map space
MainScreen as root with tab-based content switching
RoutesTabContent with route list cards + complete route (185km Maó–Maó)
RouteDetailScreen with complete stage information, map preview, and elevation chart
MapTabContent (formerly TrackingScreen) with real-time GPS display
Settings hub with language selection, about page, and contact options
Session summary overlay: dark card on map after tracking with key statistics
ElevationChart component with interactive visualization
RouteSelectionManager for cross-tab route communication
Android immersive mode hiding system navigation bar
Smart location permission handling

GPS Tracking:

Android: FusedLocationProviderClient with high accuracy in foreground service
iOS: CoreLocation with CLActivityTypeFitness and background mode
Background tracking: Foreground service (Android) / background location updates (iOS)
Process death recovery: SharedPreferences persistence + START_STICKY + automatic session restore
GPS accuracy filtering: first-fix (30m threshold) + ongoing (50m threshold)
Elevation dead band: 3m threshold to filter GPS altitude noise in statistics
Offline-first: All data saved locally in SQLDelight
Configurable intervals (5s default) and accuracy (high)
Pause detection and session management
GPS toggle button: Automatic disable on map gestures (drag, zoom), manual toggle support
Platform-specific gesture detection (MLNMapViewDelegate on iOS, CameraMoveListener on Android)
Emulator/simulator support with relaxed filters for development testing

Interactive Maps:

MapLibre integration with native rendering on both platforms
OpenFreeMap tiles for offline-capable map display
Route visualization with colored LineLayer and white casing
Start/end markers with CircleLayer (green/red)
Smart camera positioning with bounding box calculation
Aspect-ratio aware zoom for balanced route framing
Equal margins for vertical (N-S) and horizontal (E-W) routes
Smooth pan, zoom, and rotate gestures
Fixed scroll conflicts on Android with requestDisallowInterceptTouchEvent
Map preview in RouteDetailScreen (350dp height, rounded corners)
Platform-specific implementations (AndroidView, UIKitView)

Elevation Charts:

Interactive elevation profile component with Compose Canvas API
GeoJSON parsing for elevation data extraction
Haversine formula for accurate cumulative distance calculation
Smooth curve rendering using quadratic Bezier curves
Interactive tap and drag gestures for point selection
Centered tooltip with elevation and distance information
Transparent overlay (70% opacity) for chart visibility
Real-time map marker synchronization on point selection
Positioned below map for optimal user experience

Settings & Localization:

Settings screen with Material 3 design
In-app language selection (6 languages: CA, ES, EN, DE, FR, IT)
Custom LocalizedStrings system for app-controlled localization
Language persistence across app launches
Full settings localization (titles, language names)
Independent from system language settings

Points of Interest (POI):

Complete database of 190 POIs from official Camí de Cavalls website
Multilingual content in 6 languages (CA, ES, EN, DE, FR, IT)
Three POI categories with color-coded badges:
- Coastal zones (blue): Beaches, coves, coastal areas
- Natural areas (green): Protected spaces, flora, fauna
- Historic sites (red): Towers, lighthouses, prehistoric sites
Accurate coordinates corrected from official map (UTM Zone 31N → WGS84)
POI versioning system for automatic updates
Custom scraping tools for data collection and coordinate validation
Fixed 16 POIs with coordinate errors > 800m (up to 8.3 km corrections)

POI Proximity Notifications:

Real-time detection of nearby POIs during active tracking
Local notifications with POI name and distance
Tap-to-open: notification tap navigates to MAP tab and shows POI detail popup
Android: PendingIntent with singleTop launch mode, foreground service integration
iOS: UNUserNotificationCenter with delegate-based tap handling
PoiNavigationManager singleton for cross-component event coordination
Notification analytics: each notification event tracked to backend via ViewTracker (targetType=POI/DANGER_REPORT, viewType=NOTIFICATION)
Offline queue with composite PK deduplication (PendingViewEntity: targetType+targetId+viewType)
Automatic flush on connectivity restore

Animated Splash Screen:

Menorca silhouette drawn with Canvas API SVG path rendering
Route tracing animation with color-coded segments
Cross-fade to logo with parallel scale-in animation
Randomized horse/horseshoe logo variant per launch
Always-composed phases with graphicsLayer alpha for iOS performance
Smooth screen fade-out transition to main content

Weather Forecast:

Open-Meteo API integration via Ktor HTTP client
5-day forecast with daily min/max temperature, precipitation, and WMO weather codes
Custom weather icons mapped to WMO code ranges
Weather popup accessible from MAP tab floating action button
Loading and error states with localized messages

User Authentication & Social Features:

Email/password registration with email verification (multilingual templates)
Google OAuth sign-in (Android CredentialManager + iOS GoogleSignIn SDK)
Apple Sign-In (iOS only, ASAuthorizationController with NSUserDefaults email caching)
JWT session management with secure token storage
User profile with avatar upload
Likes system for routes and POIs (device-based + authenticated)
Reviews with star ratings for routes and POIs
Danger reports with photo upload, offline queue, and automatic retry
Complete Material 3 sea-blue color scheme replacing default purple
Rich card layouts for Notebook (route image backgrounds) and Danger Reports (photo carousel with swipe)
Consistent dark FAB styling across tracking screen
Dashboard: admin user activation, danger report moderation, multilingual API responses
Dashboard tables: multi-column filters (type, source, status) and sortable column headers (asc/desc) with top-aligned headers
Dashboard analytics: view counts (preview/detail/notification) and likes displayed horizontally per POI and danger report
Hardcoded POI seeding: 190 POIs with 1,140 translations in the backend for view/like/notification analytics
Blocked user protection: photo upload endpoint rejects submissions from blocked accounts with AccountBlockedException propagation
Public pages: privacy policy, support, account deletion with i18n (6 languages, Google Play compliance)

Ready for: Route navigation, statistics, and advanced features

🤝 Contributing

This is currently a portfolio/commercial project. Contributions are not being accepted at this time.

📄 License

This project is private and proprietary. No license is granted for use, modification, or distribution.

👨‍💻 Author

Stefano Russello

Portfolio Project
Target: Production app + Commercial partnerships in Menorca

📚 Resources

Camí de Cavalls Official Website
Kotlin Multiplatform Documentation
Compose Multiplatform
SQLDelight
Koin Documentation
MapLibre - Open-source mapping platform
MapLibre Compose - MapLibre integration for Compose Multiplatform
OpenFreeMap - Free tile provider

🐛 Known Issues

iOS SQLite: Requires manual addition of libsqlite3.tbd in Xcode Build Phases → Link Binary With Libraries
- This may need to be re-added after clean builds or Xcode updates
iOS Altitude Simulation: iOS Simulator ignores elevation data from GPX files (Apple limitation)
- Altitude-based features can only be tested on real iOS devices
- Android emulator correctly simulates altitude from GPX files
Voyager-Koin: Integration removed due to compatibility issues (using Koin directly with parametersOf)
iOS Map UIKitView: Uses deprecated UIKitView API (newer API available but current version stable)

🔧 Fixed Issues

GPS Toggle Button on iOS (Fixed): GPS following now correctly disables on all user gestures (was only working on first gesture)
- Root cause: Delegate loss during Compose recomposition
- Solution: Persistent delegate using remember + update block restoration
- See GPS_TOGGLE_FEATURE.md for detailed technical documentation

💡 Technical Notes

Platform-Specific Implementations

Database Drivers

Android: AndroidSqliteDriver with Context
iOS: NativeSqliteDriver (requires libsqlite3.tbd)

Location Services

Android: FusedLocationProviderClient (Google Play Services)
- High accuracy with FINE granularity for GPS-level precision
- LocationRequest with 5s interval and 2s minimum interval
- Foreground service (LocationForegroundService) owns GPS and writes track points directly to DB
- SharedPreferences persistence for process death recovery via START_STICKY
- Static StateFlow for service-to-app communication
iOS: CLLocationManager (Core Location)
- CLActivityTypeFitness for hiking optimization
- pausesLocationUpdatesAutomatically = false (never pauses during active tracking)
- Time-based throttling in delegate callback (CoreLocation has no native time interval)
- desiredAccuracy and distanceFilter configuration (min 5m)

Permission Handling

Android: ActivityResultContracts.RequestMultiplePermissions()
- rememberLauncherForActivityResult in Composables
- ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION
iOS: CLLocationManager.requestWhenInUseAuthorization()
- Polling-based permission status check
- Info.plist entries for usage descriptions

Dependency Injection

Shared appModule in commonMain
Platform-specific modules using expect/actual pattern
Android: androidContext() for Context injection
iOS: KoinApplication wrapper in @Composable
AppPreferences injection for database versioning

Map Integration

MapLibre Native with platform-specific rendering
Android: MapView wrapped in AndroidView Composable
- MapLibreMap for map instance management
- GeoJsonSource for route data
- LineLayer for route paths with casing
- CircleLayer for start/end markers
- Color.parseColor() for hex color support
- addOnCameraMoveStartedListener for gesture detection
iOS: MLNMapView wrapped in UIKitView Composable
- MLNShapeSource for route data
- MLNLineStyleLayer for route paths
- MLNCircleStyleLayer for markers
- NSData conversion for GeoJSON handling
- MLNMapViewDelegateProtocol with persistent delegate pattern
MapLayerController: expect/actual pattern for platform abstraction
OpenFreeMap tiles: Free, offline-capable tile provider
Gesture handling: Fixed scroll conflicts with pointerInput on Android
Delegate persistence: Using remember and update block to prevent iOS delegate loss during recomposition

Performance Optimizations

Database:

Indexes on frequently queried columns (location lat/lng, session timestamps)
Flow-based reactive queries for efficient real-time updates
Foreign key constraints with cascade deletes for data integrity
Prepared statements via SQLDelight for query optimization

GPS Tracking:

High-accuracy update intervals (5s default, min 2s)
Minimum distance filter (5m) to avoid excessive updates
GPS accuracy filtering: first-fix (30m) + ongoing (50m) thresholds
Elevation dead band (3m) to prevent GPS altitude noise from inflating statistics
O(1) direct track point inserts (replaced O(n) load-all/delete-all/re-insert pattern)
Emulator/simulator detection for relaxed GPS filters during development

Calculations:

Haversine formula for accurate GPS distance calculations
Incremental statistics updates (not recalculating entire session)
Efficient coordinate transformations for map projections
Smart zoom calculation with logarithmic formula for route fitting
Bounding box analysis with padding factor for optimal route visibility
Aspect-ratio compensation for balanced map framing

Data Management

All route data stored locally in SQLite database
GPX files embedded in app or downloaded to local storage
Optional backend integration for updates (not dependent on external sites)
Offline-first architecture for reliable operation without internet

Name		Name	Last commit message	Last commit date
Latest commit History 108 Commits
composeApp		composeApp
dev-proxy		dev-proxy
gradle		gradle
iosApp		iosApp
keystore		keystore
picture-sources		picture-sources
scraper		scraper
scripts		scripts
test-routes		test-routes
web		web
.gitignore		.gitignore
GPS_TOGGLE_FEATURE.md		GPS_TOGGLE_FEATURE.md
LICENSE		LICENSE
LOCATION_TRACKING_FIXES.md		LOCATION_TRACKING_FIXES.md
README.md		README.md
TEST_INSTRUCTIONS.md		TEST_INSTRUCTIONS.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

Folders and files

Latest commit

History

Repository files navigation

Camí de Cavalls

📱 Project Overview

Key Features

Business Model

Data Strategy

🏗️ Architecture

Layers

🛠️ Tech Stack

Core

Architecture & Patterns

Libraries

Dependency Injection

Database

Networking

Image Loading

Navigation

Async & Reactive

Serialization

Logging

Maps

Location

Settings

📊 Database Schema

RouteEntity

PointOfInterestEntity

TrackingSessionEntity

TrackPointEntity

RemotePoiEntity

PendingViewEntity

🚀 Getting Started

Requirements

Setup

Running the Application

Android (Build Variants)

iOS (Xcode Schemes)

DEV Environment Indicators

Building for Production

Android

iOS

🗓️ Development Roadmap

✅ Milestone 1: Foundation & Architecture (COMPLETED)

✅ Milestone 2: Business Logic & Data (COMPLETED)

✅ Milestone 3: Core UI & Navigation (COMPLETED)

✅ Milestone 4: GPS Tracking & Permissions (COMPLETED)

✅ Milestone 5: Interactive Maps & Route Visualization (COMPLETED)

✅ Milestone 6: Elevation Charts & Settings (COMPLETED)

✅ Milestone 7: POI System (COMPLETED)

✅ Milestone 8: Bottom Navigation & UI Restructuring (COMPLETED)

✅ Milestone 9: Notifications, Splash & Weather (COMPLETED)

✅ Milestone 10: Backend CRM & Remote POI Sync (COMPLETED)

✅ Milestone 11: User Engagement & Authentication (COMPLETED)

🌐 Future: Advanced Features

📝 Current Status

🤝 Contributing

📄 License

👨‍💻 Author

📚 Resources

🐛 Known Issues

🔧 Fixed Issues

💡 Technical Notes

Platform-Specific Implementations

Performance Optimizations

Data Management

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages