TrailBlazer

-3DDC84?logo=android&logoColor=white)

A native Android companion for backcountry trekking, mountaineering expeditions, and road journeys. TrailBlazer combines precision navigational instruments, astronomical ephemerides, mountain weather analytics, an offline trip planner, a GPS track recorder, and sensor diagnostics into a clean, distraction-free interface.

Built entirely with Jetpack Compose and Material 3, featuring frosted-glass chrome powered by Haze.

No Fake Data. Every value displayed is either a real physical reading, Acquiring, or Unavailable with an explicit reason (no hardware, permission denied, or sensor turned off). Values kept while the screen is paused are explicitly marked stale. There are zero simulated values, fake defaults, or background telemetry trackers.

Features

The interface is structured into four primary tabs. Every capability lives in exactly one predictable home:

Offline Stargazing Engine

The stargazing engine operates completely offline using rigorous celestial mechanics algorithms:

• Darkness Windows: Calculates full astronomical darkness (Sun below −18°) and moon-free darkness intervals across a noon-to-noon timeline. Correctly accounts for midnight sun and polar twilight.
• Interactive Sky Chart: Azimuthal equidistant projection of the 283 brightest stars (down to magnitude 3.5 from the Yale Bright Star Catalogue), all 7 major planets, the Moon, and the Milky Way galactic core (Sgr A*). Tap any celestial body to inspect its name, altitude, azimuth, and visual magnitude.
• Compass Tracking: Chart dynamically rotates with the device's true heading when held toward the sky.
• Night Trajectory Plots: Altitude profiles for all planets and the Milky Way core plotted across the night against darkness bands.
• Meteor Showers: International Meteor Organization (IMO 2026) calendar with peak dates, lunar interference, and observer zenithal hourly rates (ZHR) scaled by radiant elevation.
• Polar Alignment Assistant: Computes exact hour angle and pole offset for Polaris (North) or σ Octantis (South) to align equatorial telescope mounts.
• Night Vision & Dark Adaptation: Countdown ring for retinal rod adaptation and one-tap switch to monochromatic red night mode.

Architecture

TrailBlazer is architected into two decoupled modules following unidirectional data flow:

flowchart TD
    subgraph Hardware ["Hardware / Platform Services"]
        SM[SensorManager]
        LM[LocationManagerCompat]
        CAM[CameraX]
        MIC[AudioRecord]
    end

    subgraph AppLayer [":app (Android Module)"]
        subgraph Repositories ["Repositories (AppContainer)"]
            SR[Sensor & Orientation Repositories]
            LR[Location & GNSS Repositories]
            TR[Tracking & Room DB]
        end
        
        Reading["Reading<T> Flow (Conflated & Lifecycle-Managed)"]
        VM[ViewModels with Nav3 Routes]
        UI[Jetpack Compose + Material 3 + Haze]
    end

    subgraph CoreLayer [":core (Pure Kotlin JVM Module)"]
        Astro["Astro Engine (Meeus / JPL)"]
        Geo["Geodesy & Coordinate Parsing"]
        Atmo["Atmosphere & Weather (ISA / Zambretti)"]
        IO["GPX / KML XML Streaming"]
        TrackAlg["Douglas-Peucker & TrackStats"]
    end

    SM --> SR
    LM --> LR
    MIC --> SR
    
    SR --> Reading
    LR --> Reading
    TR --> Reading
    
    Reading --> VM
    VM --> UI
    
    VM -.-> CoreLayer
    TR -.-> CoreLayer

• :core (Pure Kotlin/JVM): Zero Android dependencies. Contains all astronomy calculations (Meeus, JPL planetary elements, IAU 1976 precession), geodesy (haversine, spherical trigonometry, Vincenty comparisons), ICAO atmosphere, Zambretti pressure forecasting, Douglas–Peucker streaming track simplification, coordinate parsers, and XML streaming GPX/KML engines. Runs unit tests on the plain JVM in seconds.
• :app (Android Application): Handles sensor acquisition via SensorSource, location via LocationManagerCompat (no Google Play Services requirement), Room persistence with keyset pagination, DataStore preferences, foreground tracking service, and Jetpack Compose UI.

The Reading<T> Contract

All hardware inputs follow a strict sealed contract:

sealed interface Reading<out T> {
    data class Unavailable(val reason: UnavailableReason) : Reading<Nothing> // NoHardware | PermissionDenied | Disabled
    data object Acquiring : Reading<Nothing>
    data class Value<out T>(val value: T, val accuracy: Accuracy, val timestampMs: Long, val stale: Boolean) : Reading<T>
}

Sensors are subscribed through WhileSubscribed(5_000) flows: they register hardware listeners only when a screen is actively observing and shut down immediately when no collectors remain.

Privacy & Offline First

• Offline by Default: All compass, astronomy, leveling, altimeter, track recording, and stargazing features work without an internet connection.
• Consent-Gated Network Calls:
  • Open-Meteo Weather: Disabled until turned on in Sky. Coordinates are fuzzed to 0.01° (~1 km) before transmission, and responses are cached for 30 minutes.
  • Place Search: Disabled until consented to on the first search. Queries go through Android's system Geocoder.
  • Short Map Links: Unwrapped via lightweight Location header inspection over HTTPS without scraping or running third-party web code.
• Contextual Permissions: Zero permissions requested at app startup. Permissions are prompted strictly in-context when tapping the feature that requires them (e.g., Camera for Sight, Microphone for Sound Meter, Activity Recognition for Step Counter).
• Zero Third-Party SDK Trackers: No analytics, no advertising, and no Google Play Services dependency.
• Data Erasure: One-tap Delete all data in Settings clears the database, cached forecasts, and DataStore settings.

Verification & Testing Suite

TrailBlazer enforces extensive automated test coverage across both JVM and Robolectric layers:

Building

Prerequisites

• JDK 21 (export JAVA_HOME=$(/usr/libexec/java_home -v 21))
• Android SDK with Platform 37 (compileSdk = 37, targetSdk = 36, minSdk = 24)

Build & Verification Commands

# Run JVM core tests and Robolectric unit tests
./gradlew :core:jvmTest :app:testDebugUnitTest

# Run code style, linting, and assemble debug APK
./gradlew :app:lintDebug :app:assembleDebug

# Assemble release APK (validates R8 shrinking and ProGuard rules)
./gradlew :app:assembleRelease

Dependency Stack

Detailed dependency definitions live in gradle/libs.versions.toml.

Documentation

Full architectural specifications are included in the repository and bundled directly into the app (Settings → Developer docs):

• ARCHITECTURE.md: Two-module architecture, lifecycle flow, and Reading<T> contract.
• SENSORS.md: Hardware sensor fallback chains, rates, declination models, and leveling mathematics.
• ALGORITHMS.md: Celestial mechanics, JPL planetary orbits, ICAO atmosphere, Zambretti weather formulas, and geodesic maths.
• TESTING.md: Test layers, golden datasets, fuzz testing strategies, and Robolectric native graphics setup.

Weather Attribution, Acknowledgements & License

• Source License: Released under the MIT License.
• Weather Forecasts: Online forecast data provided by Open-Meteo under CC BY 4.0. Free tier for non-commercial use.
• Geophysical & Map Data: Geomagnetic declination uses the NOAA / NCEI World Magnetic Model (WMM), terrain elevation uses NASA SRTM tiles, and offline vector maps are rendered with MapLibre Native (BSD-2-Clause).
• UI Libraries: Frosted-glass surfaces use chrisbanes/haze (Chris Banes, Apache-2.0).
• Historical Prototype: The previous React/WebView prototype is archived under the git tag web-final.