Your personal location timeline and trip companion
Wayfarer Mobile is a cross-platform .NET MAUI app for Android and iOS that serves as the mobile companion for the Wayfarer platform — a self-hosted trip planning and personal location timeline system. Track your location history, navigate trips offline, and share your location with groups.
Wayfarer Mobile is a privacy-first companion app for self-hosted Wayfarer servers. Location history is stored locally (SQLite) and synced only to your configured Wayfarer server. The app does not use third-party analytics or tracking by default. Background location tracking requires elevated OS permissions; review and configure tracking settings carefully before enabling continuous logging.
| Feature | Description |
|---|---|
| Timeline Tracking | Automatic background location logging with sleep/wake battery optimization |
| Timeline Export/Import | Export to CSV or GeoJSON, import with duplicate detection |
| Trip Management | Browse trips, places, segments, and polygon zones from your server |
| Offline Trip Content | Retain Trip metadata, Places, routes, Areas, and navigation data |
| Turn-by-Turn Navigation | Voice-guided navigation with multi-tier route fallback |
| Group Sharing | Real-time location sharing via SSE with colored member markers |
| Activity Types | 20 built-in activities with icons, editable per-location, server sync every 6 hours |
| Manual Check-ins | Quick location logging with activity type and notes |
| QR Setup | Scan a QR code to instantly configure server connection |
| PIN Lock | Protect your location data with app-level security |
| Queue Management | Monitor sync status, configurable limits, export queue data |
- Offline-First Architecture: Local SQLite storage with background sync, works without internet
- Smart Battery Usage: Three-phase sleep/wake optimization for background tracking (~1-3% per hour)
- Dual Navigation Modes: Trip navigation (user segments → cached → OSRM → direct) and ad-hoc navigation (OSRM → direct)
- Queue Resilience: Configurable queue limit (default 25,000), fast sync (12s/location), export to CSV/GeoJSON
Map cache note: OpenStreetMap tiles requested during interactive viewing are kept in a bounded live cache. Previously viewed tiles may remain usable while cached, but Trip downloads do not include or guarantee an offline basemap area.
- .NET SDK 10.0.400 (pinned by
global.json) - MAUI workload set 10.0.400.1:
dotnet workload restore - Platform SDK:
- Android: Android SDK API 36 and JDK 17; API 24 remains the minimum
- iOS: Xcode 26.6 on macOS 26.2 or later; iOS 15.0 remains the minimum
# Restore dependencies
dotnet restore
# Build for Android
dotnet build -f net10.0-android
# Build for iOS (macOS only)
dotnet build -f net10.0-ios
# Run on Android emulator/device
dotnet build -t:Run -f net10.0-androidTo enable background location tracking:
- Android: Requires foreground service and background location permissions
- iOS: Requires "Always" location permission and background modes enabled
Refer to the User Guide for platform-specific setup and troubleshooting.
- Open the Wayfarer Mobile app
- Go to Settings → Scan QR Code
- Scan the configuration QR from your Wayfarer server
- The app will automatically configure the server URL and authentication token
Security Note: Treat your server token like a password. If you believe it was exposed, revoke and regenerate it on the Wayfarer server, then re-scan the QR code to re-pair the app.
WayfarerMobile/
├── src/
│ ├── WayfarerMobile/ # Main MAUI application
│ │ ├── Data/ # Database entities and services
│ │ ├── Services/ # Business logic services
│ │ │ └── TileCache/ # Tile caching services
│ │ ├── ViewModels/ # MVVM view models
│ │ ├── Views/ # XAML pages and controls
│ │ │ └── Controls/ # Reusable UI controls
│ │ ├── Shared/ # Converters, behaviors
│ │ ├── Platforms/ # Platform-specific code
│ │ │ ├── Android/Services/ # Foreground location service
│ │ │ └── iOS/Services/ # CLLocationManager integration
│ │ └── Resources/ # Images, fonts, raw assets
│ │
│ └── WayfarerMobile.Core/ # Platform-agnostic library
│ ├── Algorithms/ # Geo calculations, pathfinding
│ ├── Enums/ # Shared enumerations
│ ├── Helpers/ # Utility classes
│ ├── Interfaces/ # Service contracts
│ ├── Models/ # Domain models, DTOs
│ └── Navigation/ # Navigation graph and routing
│
├── tests/
│ └── WayfarerMobile.Tests/ # Unit tests (xUnit)
│
└── docs/ # User and developer documentation (Docsify)
| Category | Technology |
|---|---|
| Framework | .NET 10 MAUI |
| Maps | Mapsui 5.1 with OpenStreetMap tiles |
| Routing | OSRM (Open Source Routing Machine) |
| UI Components | Syncfusion MAUI Toolkit (MIT) |
| MVVM | CommunityToolkit.Mvvm |
| Database | SQLite-net-pcl |
| HTTP Resilience | Polly |
| Logging | Serilog |
| QR Scanning | ZXing.Net.MAUI |
| Real-time | Server-Sent Events (SSE) |
Full documentation is available in the docs/ directory and online at stef-k.github.io/WayfarerMobile.
- User Guide - Getting started, features, troubleshooting
- Developer Guide - Architecture, services, API integration
To view the documentation locally with Docsify:
# Install docsify-cli globally
npm i -g docsify-cli
# Serve the documentation
cd docs
docsify serveContributions are welcome! This is a spare-time project, so responses may be delayed.
Before contributing:
- Open an issue to discuss major changes
- Keep pull requests small and focused
- Follow the existing code style (XML comments, strict MVVM)
- Include tests for new functionality
See the Contributing Guide for more details.
WayfarerMobile refers to the official companion app for the Wayfarer project. Forks and modified redistributions should use a different name to avoid confusion or false association.
This project is licensed under the MIT License - see the LICENSE file for details.
Map data © OpenStreetMap contributors