TrailQuest

A gamified hiking trail app that transforms hiking into an interactive adventure. Using GPS tracking, challenge points, and leaderboards, TrailQuest motivates users to explore and complete trails around Melbourne. Features include trail navigation, quiz challenges, photo opportunities, and a points-based reward system.

🎯 Key Features

• Interactive trail navigation with real-time GPS tracking
• Challenge points with quizzes along trails
• Photo capture and sharing capabilities
• Points system and leaderboards
• Real-time step counting and distance tracking
• Trail completion tracking
• Multiple difficulty levels
• Social features with user reviews

---

✨ Current Features

• Interactive Google Maps view of Melbourne trails.
• Trails are fetched from Firestore (collection: trail_v4).
• Each marker opens a trail detail screen with distance, estimated time, and route visualisation.
• Supports polylines to render the full trail path.
• Clean architecture with MainActivity, HomeMapScreen, and TrailDetailScreen.
• Shared data model (Trail.kt) that includes both legacy fields and the new schema.

---

📱 Tech Stack

• Android Development

  • Kotlin + Jetpack Compose for UI
  • Coroutines for asynchronous operations
  • Material 3 Design System
  • ViewModel + StateFlow for state management

• Maps & Location

  • Google Maps SDK + Maps Compose
  • Location Services for GPS tracking
  • Polyline encoding/decoding

• Backend & Storage

  • Firebase Firestore for trail and user data
  • Firebase Authentication
  • AWS S3 for photo storage

• Sensors & Hardware

  • Step Counter sensor integration
  • Camera API for photo capture
  • Activity recognition

• Development Tools

  • Python scripts for data import
  • Gradle for build automation
  • JUnit and Compose testing tools

---

⚙️ Importer Script

1. Melbourne Dataset Importer

The importer (scripts/import-walks-3.py) fetches the Self-Guided Walks dataset from the City of Melbourne and writes it into Firestore in a normalized format.

Requirements

Install dependencies:

pip install -r scripts/requirements.txt

Config

Create a file firebase.local.yaml in the scripts/ folder: You should export a service account JSON file which contains a private key from Firebase Console.

project_id: YOUR_FIREBASE_PROJECT_ID
service_account: path/to/serviceAccount.json
collection: trail_v4
dataset_url: https://data.melbourne.vic.gov.au/api/explore/v2.1/catalog/datasets/self-guided-walks/records

Run the importer

cd scripts
python import-walks-3.py --keep-points

Flags:

• --keep-points: also store downsampled trailPoints for detailed route rendering.
• --debug: print skip reasons and sample fields during import.

2. Sydney Dataset Uploader

Sydney trails are manually curated from KML data and saved locally as JSON (e.g., sydney_trails_v4_schema_updated.json).

Use the new scripts/firestore_manager.py script to upload the Sydney dataset into Firestore.

Example usage:

python3 scripts/firestore_manager.py \
  --key trailquest-service-key.json \
  --collection trail_v4_update \
  --upload sydney_trails_v4_schema_updated.json

This script automatically:

• Converts {lat, lng} dictionaries into proper Firestore GeoPoint objects
• Normalizes timestamps (updatedAt) to numeric milliseconds
• Inserts or updates each document in the specified Firestore collection

Optional: Backup & Duplication Utilities

Before uploading new datasets, you can backup or duplicate existing Firestore collections.

Backup existing collection

python3 scripts/firestore_manager.py \
  --key trailquest-service-key.json \
  --collection trail_v4_update \
  --backup trail_v4_update_backup.json

Duplicate collection (for versioning or sandbox testing)

python3 scripts/duplicate_collection.py \
  --key trailquest-service-key.json \
  --from trail_v4_update \
  --to trail_v5_backup

Output in Firestore

Each trail doc includes fields such as:

• trailId, trailName, trailDescription
• trailDistance, trailEstTime, trailType, terrainType
• trailAmenities, trailAccessibility, trailSourceUrl
• activityType, trailMedia
• bbox, trailPoints, path_polyline, updatedAt

---

🗂️ Repository Structure

TrailQuest/
│
├── app/                   # Android app source
│   ├── ui/                # UI components (HomeMapScreen, TrailDetailScreen, etc.)
│   └── data/              # Data models (Trail.kt)
│
├── scripts/               # Importer scripts + requirements.txt
│   ├── *.py
│   ├── requirements.txt
│   └── firebase.local.yaml (not committed)
│
└── README.md

---

🧪 Testing Guide

Running Tests

In Android Studio

1. Right-click on the app folder
2. Select Run 'All Tests' to run both unit and instrumented tests
   • Or select Run 'Tests in app' for unit tests only
   • Or right-click specific test files to run individual tests

Test Cases

Unit Tests (app/src/test/)

• Challenge completion logic
• Location-based triggers
• Basic calculations (points, distance)
• Google Maps and basic geographical calculations